Feature proposal: New, Standard Documentation System

[Basil Mohamed Gohar]

On Mon, 2008-12-01 at 12:42 +0200, Basil Mohamed Gohar wrote:
> 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?
> 
By the way, I feel the work towards man pages is conducive to producing
better documentation across the board, including on the docs site as
well as guides/tips/whatever on the Wiki.

This is one of the main reasons, in fact, that I feel we should push for
man page updates.  I feel it will filter out, including upstream, to the
maximum benefit on all fronts for documentation purposes.

Should I present this idea to the docs project, pending the agreement of
most, if not all, those involved in this discussion?  I'm mulling the
idea of even heading it, if no one else is more appropriate for the
task...