Quoting [email protected] ([email protected]): [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. _______________________________________________ Dng mailing list [email protected] https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
