Quoting Steve Litt (slitt@???):
> Rick Moen <rick@???> wrote:
>
> > http://linuxmafia.com/~rick/lexicon.html#moenslaw-documentation
> >
> > Moen's Law of Documentation
> >
> > "The more you write, the less they read."
>
> Not true, if you structure the writing correctly. Especially now that
> we have hyperlinks, it's easy to write good and non-ambiguous docs.

Well, I've seen the effect I describe at said lexicon item play out in
the real world, over and over, with writings from untold numbers of
technical people. However, I admire your optimism.

Absolutely, I do endorse your notion that part of the problem is reliance
on excessively linear prose. As I said, IMO that's a big part of the
structural problem with Eric's and my essay.

> Yes, but in a "how to do it" document (like documentation on a distro's
> install procedure), once you've articulated the steps and substeps and
> what could go wrong and how to deal with it, you're done.

I _really_ admire your optimism. ;->

> All things being equal, concise is always better than rambling. But man
> pages are concise....

Even the one for GNU find? ;->