>Which might result in my dumbing it down too much, but that's another problem.
It's a risk worth taking. Think of the audience as reading at the
level of 5th-graders or so. That doesn't necessarily mean dumbing
it down. It does mean picking and using consistent terms for things,
writing clearly and concisely, and so on.
The audience for technical documentation, no matter *how* intellectually
advanced, includes very few people who actually *read* it at their
"advanced" level. The vast majority of readers instead dabble in it,
here and there, while focusing most of their (pertinent) mental activity
on *other* things, like the various jobs they're actually trying to
accomplish (which often only tangentially require figuring out how to
use some piece of software).
Avoiding dumbing it down is important, though, because advanced readers
might accidentally misinterpret dumbed-down writing. If you can't
see a way to bring up an important option, or facility, early on, while
keeping things clear, go ahead and *say* that, for example -- a footnote
or a parenthetical paragraph can let advanced readers know that, indeed,
Greater Things are afoot, without unduly confusing those who are
just begining to grapple with the topics presented.
I miss the days of my youth, when I actually had the time *and* the
inclination to read entire manuals on software over and over again,
until I'd nearly committed them to memory. That may be the best way to
learn about new products today. It probably is the best way to learn
about qmail, given the sort of documentation it has (which probably
has a very high "truth ratio", but certainly has much lower quality
as technical documentation than the software itself -- which doesn't
actually say much that's bad about the documentation).
But, the best way to *write* about new products today is to understand
that many readers will look at, say, a section, or even screenful,
of documentation every couple of days, and occasionally look up terms
in the index (following only one or two of the references), *at most*
during their initial attempts to use the product.
Such readers are best served by simplified roadmaps, which in turn
are backed up by clear, direct, and consistent chunks of documentation.
tq vm, (burley)
