Re: Feature proposal: New, Standard Documentation System

[Basil Mohamed Gohar <abu_hurayrah hidayahonline org>]

On Mon, 2008-12-01 at 09:28 +0100, Matej Cepl wrote:
> On 2008-12-01, 01:45 GMT, Michael Cronenworth wrote:
> > Man pages, while informative, are limited. If examples or 
> > detailed information are required then you're back to Google 
> > searching.
> 
> Yes, there are many manpages which are pretty bad. But expanding 
> content won't happen by switching to different format, but fixing 
> each manpage. Yes, one at the time.
> 
> > Two hours? I should hope to create something in 10 minutes.
> 
> Two hours include learning curve. After writing one manpage and 
> learning how to do it, including collecting appropriate tools, it 
> should be as fast as writing with anything else. I don't think 
> that two hours of learning is too high price for creating 
> structured, long-lasting documentation.
> 
> Best,
> 
> Matěj
> 
I've never written a man page or much documentation myself, but I think
this is a great area where non-programmers (or at least, those that
don't know the languages that are used inside of Fedora & other free
operating systems) can contribute back to the project.

If someone could setup a SIG for man page conversion or just leverage
the documentation team and make a focus on teaching how to do man pages,
I could see this bits of this task being chipped away significantly on
the road to F11.  I know that I'm definitely leaning towards the idea of
writing one or two man pages, because I've run into the missing-man-page
problem too often.

Here's a suggested action plan (forgive me if I am out of place for
suggesting it):

1) Identify which packages are missing man pages altogether in Fedora
	-- these should get top priority
	-- we can see if Debian or other projects already have some
		-- acceptable-licensing-pending, of course
2) Identify which packages having sub-par man pages
	-- after fulfilling 1), this should be the next priority
	-- similar methodology to 1), find ones that already exist first
3) Develop a "stub" template for packages that have no man pages
available
	-- at least we can include command-line arguments, authorship,
		web links for more info, etc.
		-- at first this isn't much better than -h/--help, but
			we can at least let it be a start
4) Once we have all of this information prepared, then we can get to
work on forming a project around this group, preparing a page in the
wiki with the packages that need man pages or whose man pages need
improvement, etc.
5) ???
6) Profit!

How does that sound?