:: Re: [DNG] Fwd: Re: What should an …
Góra strony
Delete this message
Reply to this message
Autor: Rick Moen
Data:  
Dla: dng
Temat: Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
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? ;->