Online Documentation. New! Improved!

Subject: Online Documentation. New! Improved!
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Wed, 16 Oct 1996 23:36:23 PDT

I'm perplexed. People keep telling me how on-line documentation needs
to be different from other documentation, and yet all the best on-line
documentation I've used is exactly the same as its printed counterpart.

Take QuickBooks, for example. Its on-line documentation stinks.
It has about three levels of on-line help: pop-ups that obscure your
work and tell you nothing, on-line help that tells you that you enter
names in the NAME field, and on-line manuals that tell you that you
enter names in the NAME field. Duh!

(Whoops! I almost forgot the duh-level audio help for people
who can't read.)

This is not only duh-level documentation, but it's simultaneously
fragmentary and redundant.

I've been saddled with many applications whose documentation consists
of mazes of twisty passages, all different. No structure, spotty
coverage, lots of duh-level stuff repeated seventeen times. It's

In a book, you can flip through the pages, look at the table of contents,
or look in the index. Much of the on-line documentation I've been using
has NONE of these features. A top-level "topic list" replaces the table
of contents and omits about 90% of the information. A search-by-keyword
function omits virtually all of the utility of the index. The document
is a maze of twisty passages, so you can't even flip through it, since
it has no linear structure.

Text adventures were sort of fun in 1980, but it's old hat now.

On the other hand, I have also dealt with on-line manuals that were
designed to be real manuals, with indexes, tables of contents, and
internal cross-referencing. The on-line version was fully hyperlinked,
and a nifty search engine allowed you to fish for topics if the
professional, three-level index failed you. You could also print
the thing out as a manual, if you wanted to.

(Interleaf's on-line manuals are the best, though some others are
pretty good, too.)

So, thus far, my best experiences with on-line documentation has been
with real manuals, and my worst have been with documentation that was
designed(?) specifically for on-line use, with everything done right
and proper according to the rules du jour (such as keeping topics short
by omitting anything that verges on complexity).

-- Robert
Robert Plamondon, President/Managing Editor, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139

Previous by Author: Re: Turning Over a New Interleaf
Next by Author: Re: Online Documentation. New! Improved!
Previous by Thread: TW-Opening - Phoenix, AZ
Next by Thread: Re: Online Documentation. New! Improved!

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

Sponsored Ads

Sponsored Ads