Feature proposal: New, Standard Documentation System

Basil Mohamed Gohar abu_hurayrah at hidayahonline.org
Mon Dec 1 10:42:14 UTC 2008

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
	-- 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?

More information about the fedora-devel-list mailing list