On Tue, 1 Jan 2019 19:04:32 -0800
Rick Moen <rick@???> wrote:

> Quoting golinux@??? (golinux@???):
>
> [much concentrated wisdom]
>
> > The best documemntation will be useless if no one reads it.
> [...]
> > Even though information is already available on the site and
> > elsewhere, quite often there will be questions that could be readily
> > answered with a little effort on the user's part. So it is not a
> > lack of information problem but a "you can't fix stupid" problem.
> > Bloating the guide won't change that human behavior.
>
> Reminds me of a couple of things I've realised through many years
> observing where documentation and user education works and where it
> doesn't -- and pondering why. First of two is this:
>
> 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.

>
> Although any piece of writing can be improved, even the best
> examples, especially of technical writing, no matter how excellent,
> will garner requests for _more detail_ -- far past the point of
> reason.

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. Any requests
for further info, such as theoretical underpinnings, can be done in a
separate document.

> Why? Because, most often, a questioner's immediate reaction
> (to not instantly understanding) is to claim that insufficient
> information was provided, whether such is true or not. The longer and
> more detailed any subsequent, further explanations are, the more
> difficulty target readers will have in finding what they need, and
> the more they'll demand an even thicker forest of explanations to get
> lost in.

Not if it's written right.

>
> Thus, greater conciseness often does _much more good_ than do
> longer & more detailed explanations.

All things being equal, concise is always better than rambling. But man
pages are concise, yet they tend to be of value more as a reminder to
those who already know the software than those approaching it for the
first time.

Anyway, I'm a big believer in giving just enough data so nothing's
ambiguous and all terminology is defined.

SteveT