OpenSource documentation problems

[Paul Rubin]

"Adriaan Renting" <renting at astron.nl> writes:
> He seems to think the GNU man pages are nice, but I find them very
> awkward as they have no hierarchical organization, and most miss examples.

The GNU man pages are an afterthought to meet expectations of Un*x
users who were used to man pages and the man command.  The good GNU
docs are in texinfo format, not man pages.  They have lots of examples
and they hierarchical structure and were designed to be navigated with
a pre-www hypertext browser or alternatively generate printed manuals.
These days there are also programs to render them as html so you can
navigate them with web browses.

> I do agree that a lot of OSS projects seem to lack somewhat in the
> documentation department, compared to a lot of commercial
> software. I would give the man page of gcc as an example, it's just
> one 6600 line blurb. The other part where a lot of OSS seems to be
> lacking is user interface design.

The man page only exists for the sake of users who insisted on having
a doc in that inferior format.  The "official" gcc doc is at:

   http://gcc.gnu.org/onlinedocs/gcc-4.0.1/gcc/

> The big question is: how to attract more doc writers to the OSS movement?

It's traditionally been a problem.  The FSF has hired a number of tech
writers over the years, and paid them to write docs.  That's one way.