Re: Configure.help editorial policy

Rob Landley (landley@trommello.org)
Fri, 21 Dec 2001 19:23:13 -0500


On Friday 21 December 2001 05:36 am, Mike Jagdis wrote:
> Eric S. Raymond wrote:
> > I guess it's a pretty quiet week in kernel-hacker land. Must be,
> > otherwise people would have better things to do than argue over KB
> > vs. KiB. The alternative would be to conclude that significant
> > portions of the lkml population prefer flaming to coding, and that
> > couldn't possibly be the case, could it?
>
> Surely not?
>
> > However. In the *absence* of a clear consensus, I will follow best
> > practices. Best practice in editing a technical or standards document
> > is to (a) avoid ambiguous usages, seek clarity and precision; and (b)
> > to use, follow and reference international standards.
>
> "Best" practice? That's the *only* practice! Guesswork and assumption
> has no place in technical documentation!

This may be why Andrea Arcangelli refuses to write any documentation at all,
Linus seems to have a prediliction for dropping documentation-only patches,
why the stuff in /linux/documentation has fallen up to two years out of date
at times, and why "Rusty's Unreliable Guides" (the best source of
documentation on the netfilter code, made available by the author himself at
"http://netfilter.samba.org/unreliable-guides/") says, and I quote:

-----

The Linux Documentation Project has the noble goal to `create the canonical
set of free Linux documentation'.

The Open Source Writer's Group wants `to put together a comprehensive "card
catalogue" of Open Source and Open Source-related documentation'.

On the other hand, my pet hamster dressed up in a penguin suit, and appeared
to me in a dream, telling me to write documentation for random stuff, and
include lots of obscenities.

The LDP guys no longer return my EMails (from me or my hamster).

-----

On the net, the way to get information isn't to ask questions, but to post
errors. Questions get ignored more often than errors go unflamed. Perfect
documentation, like perfect code, isn't something you wait until you have
before proceeding.

Rob
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/