Feature proposal: New, Standard Documentation System

[Camilo Mesias]

Hi,

>> > >Debian forces all programs to come with a man page.  If one is
>> > >missing, this is considered a bug and packagers have to write one.
>> > >
>> > >http://www.debian.org/doc/debian-policy/ch-docs.html
>> > >
>> > >This would be an excellent idea for Fedora to follow (and we can,
>> > >license permitting, use the Debian man pages).
>> >
>> > My 2 cent: It would be way better for everyone to get those man pages
>> > upstream.
>> >
>> > One reason for that: If you add man pages from debian to a fedora
>> > package then you have to recheck every now and then if the man pages are
>> > still up2date. That afaics often tends to be forgotten (I'm guilty
>> > myself here).
>>
>> +1. Also I'd make it a SHOULD item in review guidelines.

I agree with this. Fedora has a lot of good new technology that is let
down by the lack of readily available documentation. Examples include
pm-suspend (no man page but pretty webpages) the greatly understood
selinux (manpages but not enough FAQs or accessible tutorials),
NetworkManager (what does it do in this release?), packagekit, dbus,
etc. Wouldn't it be great if there was a guaranteed way to find
relevant docs for every bit of software in the distro?

I think Michael's mistake is to think that a new tool is the way to
achieve this. Even the most impressive shiny new tool would not make
people create new documentation. What's needed IMO is procedures,
standards and a bit more linking between existing documentation. What
if we had some metrics for documentation, and a league table where
maintainers could see how they are doing wrt. their peers?

-Cam