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."

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. 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.

Thus, greater conciseness often does _much more good_ than do longer &
more detailed explanations. Or, what might be needed is better indexing,
or following the classic journalist's inverted pyramid format
(http://mtsu32.mtsu.edu:11178/171/pyramid.htm), or the short
answer / long answer format I often use -- or just a polite suggestion
to Read the Friendly Manual (or Search the Friendly Web).


The second: As you may recall, I ended up collaborating wit Eric S.
Raymond in co-authoring our essay 'How to Ask Questions the Smart Way'
(after we happened to chat circa 2000 and found that we were
independently writing the same thing). The end-result has been
astonishingly popular (e.g., linked to by a vast number of projects'
help pages), and we kept adding additional subtopics readers
requested for quite a few years. (IMO, the essay has some damning
problems, but that's a different topic.[1]) But Eric was very dismayed
that, the more we improved the essay and polished out its most-noted
flaws, the dumber people's subsequent objections to it became -- in many
cases, suggesting they had completely disregarded what said and
attributed to it attitudes and claims that just weren't even remotely
present.

I pointed out that, no, Eric, you actually have it backwards:
Initially, there were a number of reasonable objections to the text. We
did a pretty good job fixing those through iterative improvement over
quite a few years. Whenever you've satisified all of the reasonable
objections, what you're left with are the unreasonable ones, e.g., those
who will complain about a text without reading it at all, or read it so
poorly as to comprehensively misunderstand it.

Eric had fallen prey to a variant of the fallacy of composition
(https://en.wikipedia.org/wiki/Fallacy_of_composition), which 'arises
when one infers that something is true of the whole from the fact that
it is true of some part of the whole'.

It's worth remembering that the better suited to task a piece of
documentation is, the more head-scratching the remaining complaints will
tend to become (not that any documentation can't be improved).


[1] Basically, it's too long-winded and too linear. Linear is an
artifact of the DocBook toolset. The excessive length is because we
kept good-naturedly complying with requests to add things. IMO, what
has resulted is an essay very popular with the people who don't need it,
e.g., project leaders, but almost totally disregarded by its intended
audience.