Re: Lousy vs. good writing, good vs. bad manuals

[Mike Starr <mike -dot- starr -at- PLATINUM -dot- COM>]

Diane Gutierrez suggested we need to "get away from boring, three-pound,
uninformative manuals and also from unhelpful, obscure and
explanation-deficient pamphlets that leave too many questions unanswered." I
have to respond to both aspects of what she said because I think we need to
make some basic distinctions.

I'm one of those folks who believes that having a LARGE printed manual isn't
necessarily a bad thing and that having a SMALL printed manual (or pamphlet as
Diane rightly described them) isn't necessarily a good thing. Let me qualify
this by saying that over the last several years, I've worked on documentation
projects for software products that are both incredibly powerful and
incredibly complex. These products got that way because the customers demanded
both the power and the complexity or because the development team found that
they could dramatically expand the capabilities of the product in whole new
directions.

The current mindset seems to be that we should provide purely PROCEDURAL
documentation, telling the users only how to do the most common tasks. But, if
we do that, where do they go to find out what the result is when they change
the setting of that obscure variable on a sub-dialog box that they wouldn't
even see if they do the common tasks?? The answer is that we need to also
provide them with complete REFERENCE documentation, so that they can find out
exactly what every control they're presented with is used for, how to use it
and why they might want to use it.

Now, there are those who'll say that's what "What's This" help is for, but
I've also heard many espouse just using brief descriptions in the pop-up
topics created for "What's This" help. So, if we follow the generally accepted
norms, that leaves us with a pamphlet telling the user how to do a few of the
most common tasks, "What's This" help that only provides a general description
of the function of a control and absolutely nothing to tell the user what the
nitty-gritty details are. Thus, re-entering triumphantly from stage right, we
have the REFERENCE portion of the printed manual. And, when the product is
both incredibly powerful and complex, it's entirely conceivable that the
complete documentation could end up being a LARGE manual. And that's okay with
me.

Diane points out the success of the "... for Dummies" books. Yep, they're
successful because users aren't satisfied with what we're giving them. It
would occur to me that it would be a huge slap in the face to me if someone
published a "... for Dummies" book for a product I created the documentation
for. It would tell me that I did such a lousy job of it that there's a market
for "real" documentation for it.

Mike

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