Gentoo Logo
Gentoo Spaceship




Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-desktop
Navigation:
Lists: gentoo-desktop: < Prev By Thread Next > < Prev By Date Next >
Headers:
To: gentoo-desktop@g.o
From: Lindsay Haisley <fmouse-gentoo@...>
Subject: Re: What "just works" and what doesn't?
Date: Sun, 17 Oct 2004 15:13:27 -0500
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

References:
What "just works" and what doesn't?
-- Donnie Berkholz
Re: What "just works" and what doesn't?
-- Mike C. Fletcher
Re: What "just works" and what doesn't?
-- Lindsay Haisley
Re: What "just works" and what doesn't?
-- Jason Wong
Navigation:
Lists: gentoo-desktop: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: What "just works" and what doesn't?
Next by thread:
Re: What "just works" and what doesn't?
Previous by date:
Re: Re: Kernel_2.6/devfsd/SCSI/USB/Digital Camera problem
Next by date:
Re: What "just works" and what doesn't?


Updated Jun 17, 2009

Summary: Archive of the gentoo-desktop mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.