Re: writing online documentation

Subject: Re: writing online documentation
From: Paul Goble <paulg -at- COL -dot- HP -dot- COM>
Date: Fri, 20 Aug 1993 15:19:40 GMT

Gary Beason (bubba -at- expert -dot- cc -dot- purdue -dot- edu) wrote:
: I have a question about writing online documentation, about how to--or
: whether to--handle trouble shooting.
: And I've noticed that few online documentation systems have a trouble
: shooting guide.

Let's divide trouble-shooting information into a few categories, then I'll
give my reactions about a) where the information should appear and b) why
it doesn't appear in most online documentation:

1. Error messages

Any error messages produced by the system should be clear and
self-explanatory. If necessary, you can add a "press here for
further explanation" button. In practice, developers make the
simplifying assumption that the existing error messages ARE
self-explanatory, thus eliminating the work of making them
really usable.

2. Fatal installation/system problems

These tend to be problems that prevent the use of the software
altogether, so online explanations would be inaccessible. These
should, and usually do, appear in the printed documentation.

3. Usage problems

These are the most common problems, such as when a user gets in
a jam after choosing the wrong command. Problem-solving
information should appear anywhere and everywhere the user is
likely to look for it: in context-sensitive help and as a part
of the online task and reference information. It doesn'
necessarily need to be part of a separate problem-solving guide.

In practice, information about what problems users will REALLY
encounter can come only from usability testing with real users.
That takes effort, time and money. So for most products, nobody
even knows which problems to document.

Does this fit your experience?

: environment.) It struck me as a marketing or sales decision *not* to
: include problem-oriented online documentation.

I don't think it's so much a decision not to include problem-oriented
info as it is a decision that other things are more important. As a
user advocate and as a perfectionist, I'd like to include the
problem-oriented info. But when it's one month before ship date, and I
have a choice between spending my time on (1) a problem-solving guide or
(2) something else which will have a *direct* and *significant* effect
on sales (e.g., a snazzy demo program), guess what I'll choose? Guess
what my boss will choose to do to my paycheck if I choose (1)? :-)

One of the biggest challenges in my job is to become really efficient at
the routine "must-do" tasks (like simply documenting what features are
present in the product) so that I have time to improve the product and
the documentation for real user tasks.

--------======= * =======--------
Paul Goble
Hewlett-Packard Colorado Springs Division
Learning Products Engineering
paulg -at- col -dot- hp -dot- com

Previous by Author: Re: degree programs
Next by Author: Re: What is ADP?
Previous by Thread: Re: writing online documentation
Next by Thread: Re: writing online documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads