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.
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
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
How does that sound?
More information about the fedora-devel-list