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
1 I'd like to add a point here with regard to documentation. The Gentoo
2 Documentation Project Team is pretty good about this in general, but it's
3 not in the Documentation Policy page, and there's just enough documentation
4 around (most of it non-Gentoo) that falls down on this point that it's worth
5 a mention.
6
7 There is absolutely no substitute for examples in documenting a facility,
8 especially with regard to config file syntax. I've seen some config file
9 man pages (e.g. devfsd.conf(5)) that are very long on formal syntax
10 definitions and very short on examples which are much more labor intensive
11 to understand than they would be if the author(s) included half a dozen
12 lines or so for a good example or two. The man page for sudoers(5) is a
13 good example of something that's very helpful in this regard. Not only is
14 the formal syntax definition very logical and complete, but the man page
15 closes with some really fine examples.
16
17 Gentoo docs are, by and large, very good not only with examples, but also
18 with specific instructions for config setups which 'just work' and which
19 also serve as examples for understanding the how/why of the setup. I can't
20 say the same for some other distributions.
21
22 --
23 Lindsay Haisley | "Everything works | PGP public key
24 FMP Computer Services | if you let it" | available at
25 512-259-1190 | (Travis W. Redfish) | <http://www.fmp.com/pubkeys>
26 http://www.fmp.com | ("The Roadie") |
27
28 --
29 gentoo-desktop@g.o mailing list