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 |