Re: Good/bad docs

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

The tech writing business is subject to management fads, just like any
other.  There's a false minimalism fad that goes, "95% of the users
never read the manual (and never learn how to use the product well),
so why bother with documentation?"  This is both a false premise and a
false concluseion.  Even if the premise were correct, the conclusion
should be, "...so let's make the operation of our software
transparently simple."

But the premise isn't correct, because basing decisions on percentages
of all users contains an implicit assumption that all users are the
same.  The results are as whimsical as if Ford decided, "98% of the
people who buy our cars don't use the shop manual, so let's not create
one."  Mechanics need a shop manual even if drivers don't, but
software companies seem unable to distinguish between the needs of
least-common-denominator users, power users, and administrators.  All
users are assumed to be naive users.  (While Microsoft has some
documentation for administrators and the like, it is not mentioned in
the main documentation, as far as I can tell.  You have to rummage
around on the Web site.)

This is complicated by the fact that on-line documentation conceals
its own structure and context if you aren't careful to preserve it.  I
often go hunting around for detailed information on some feature or
other, and trip over idiot-level fluff, such as glossary entries, in
my search for real meat.  Often the real meat doesn't exist.  Even if
it does, it's a needle buried in a haystack of statements of the
bloody obvious.

Thus, since it's hard to find stuff in most on-line manuals, you can
leave all the good stuff out and people won't even be sure it's
missing.

        -- Robert

--
Robert Plamondon * High-Tech Technical Writing
36475 Norton Creek Road * Blodgett OR 97326
541-453-5841 * Fax: 541-453-4139
mailto:robert -at- plamondon -dot- com * http://www.pioneer.net/~robertp

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=