Gentoo Archives: gentoo-desktop

From: Lindsay Haisley <fmouse-gentoo@×××.com>
To: gentoo-desktop@l.g.o
Subject: Re: [gentoo-desktop] What "just works" and what doesn't?
Date: Sun, 17 Oct 2004 20:13:53
Message-Id: 20041017201327.GL6508@fmp.com
In Reply to: Re: [gentoo-desktop] What "just works" and what doesn't? by Jason Wong
I'd like to add a point here with regard to documentation.  The Gentoo
Documentation Project Team is pretty good about this in general, but it's
not in the Documentation Policy page, and there's just enough documentation
around (most of it non-Gentoo) that falls down on this point that it's worth
a mention.

There is absolutely no substitute for examples in documenting a facility,
especially with regard to config file syntax.  I've seen some config file
man pages (e.g. devfsd.conf(5)) that are very long on formal syntax
definitions and very short on examples which are much more labor intensive
to understand than they would be if the author(s) included half a dozen
lines or so for a good example or two.  The man page for sudoers(5) is a
good example of something that's very helpful in this regard.  Not only is
the formal syntax definition very logical and complete, but the man page
closes with some really fine examples.

Gentoo docs are, by and large, very good not only with examples, but also
with specific instructions for config setups which 'just work' and which
also serve as examples for understanding the how/why of the setup.  I can't
say the same for some other distributions.

-- 
Lindsay Haisley       | "Everything works    |     PGP public key
FMP Computer Services |       if you let it" |      available at
512-259-1190          | (Travis W. Redfish)  | <http://www.fmp.com/pubkeys>
http://www.fmp.com    |    ("The Roadie")    |

--
gentoo-desktop@g.o mailing list