Re: writing online documentation

[Faith Weber <weber -at- EASI -dot- ENET -dot- DEC -dot- COM>]

Hi Gary,

I agree with Chuck regarding what problem-solving sections are
usually called in hardware and software manuals. Regarding the
larger question I think you were asking, I think this type of
information should be included in online documents. For me, as
a user, one of the most irritating things about the online help, etc.
I use is that it *doesn't* tell me what to do when I run into
trouble, which is the time I most often go looking for information
in Help anyway!

I've heard the "marketing" argument before, but I just don't
agree with it. Of course if you provide problem-solving information,
you should present it with the attitude that the software is
perfectly good, but there are some areas where users may get stuck,
and you want to help the reader avoid those areas. As a reader,
I tend to really *appreciate* software vendors who have the foresight
to look for trouble spots and tell me how to handle them.

One thing I wonder, though: do you need to have a separate section
for problem-solving? My inclination when doing my own paper docs is
to put the information wherever it's pertinent. For example, if the
problem has to do with setting up the display correctly, then
somewhere in the section about setting up the display I would say
"Be sure to do this, this, and this. Otherwise that [undesirable
result] may happen." It's sort of a preventive approach, and rather
than saying there's a problem you might encounter with the software,
you're saying "You, the user, have to use this a certain way if
you want to get good results."

Faith Weber
weber -at- easi -dot- enet -dot- dec -dot- com