There are, it seems to me, two purposes to which documentation is put.

Most people consulting the documentation are attempting to fix something that’s broken, or otherwise get something to work. This is the “tell me how to do it” variety.

A smaller number of people consult documentation in order to gain a deeper understanding of how things work, and why. The motivation for this is varied, of course, but it’s a different goal than simply getting something working.

The former way of looking at docs is very short term, immediate, crisis. The latter is more long-term. Generally, if one reads the docs and understands how things work, and why, they tend to have fewer of the crisis situations in which they need to get something working.

There’s a documentation bug about the Order directive which is grounded in this very difference. The Order syntax is annoying and unintuitive, if you don’t understand how it works, and why. Most people don’t want, or need, to understand why. And, in this case, the “why” is not particularly simple. Folks just want to know how to get their allow and deny directives working. And the docs currently don’t really help them do that. At least, not right now. Hopefully they will in a few days.

My goal in documentation is generally to first address the “how do I fix it” question, because that’s the most frequent use of the docs. I don’t necessarily think that folks *should* have to understand the inner workings of the configuration directory-scope merging mechanism in order to keep the nasty spammer out of their content.

However, most of the technical documentation that I encounter is of the “how does it work” variety, and a great deal of it doesn’t even do a good job of that.

I’m just rambling, and observing. I don’t know what the solution is. There’s certainly a lot of “howto”‘s out there, and so many of them are either very specific to a particular scenario, or just plain wrong. These are a well-meaning approach to the problem, but often go astray.