Re: writing online documentation

[Paul Goble <paulg -at- COL -dot- HP -dot- COM>]

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