Re: Online Documentation. New! Improved

Subject: Re: Online Documentation. New! Improved
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Sat, 19 Oct 1996 19:35:18 PDT

>But I think there is an important, but subtle, difference between the
>goals of a manual and a help system. When I hit that F1 key, I have a
>particular question I want answered. When I open the manual, I may have a
>particular question (in which case I'm already unhappy, because the help
>system didn't answer it, and if I see the same non-answer, I'm going to
>be upset) or I may want to learn something.

>The magic help system works like this:
> I hit the button and my question is answered.

>The magic manual works like this:
> I, an ignorant but eager learner, read the book and become an expert.

I think that this is a naive expectation. The user cannot normally
be expected to know in advance which operations can be dealt with by
a push of a button, and which require a more Byzantine approach.
Any wide separation between on-line help and on-line documentation
requires that the user know in advance which catagory a question
falls into.

In a world where hyperlinks, CD-ROMs, and the Internet exist, such
a wide separation stikes me as almost completely pointless. Hitting
the HELP key when you are on a particular field should give you access
to all the relevant documentation. Probably the generic sort of help
screen should be on top, but the links to everything else of interest
should be there, too. Why not?

The Netscape documentation works this way. A certain amount of stuff
in on-line (your mileage may vary; I use it on a SPARCstation), and
the rest is on the Web, but it's all linked together. I can get
arbitrarily technical reference manuals in moments. Cool!

>Things have changed lately. The term "on-line documentation" is no longer
>a synonym for "help system," and the manual may not be paper.

People who have approached the problem of on-line documentatoin from
the PC world may not realize how truncated the PC solution was. In
a world where all software was distributed on floppy disk, and systems
had very little mass storage and no CD-ROMs, only vestigial on-line
documentation was practical.

In the workstation world, on the other hand, relatively massive on-line
documentation was the rule by the end of the 1970's. VMS (remember VMS?)
had an extensive help system, and many UNIX installations had the complete
manual set on line. In fact, the manual set and the 'man pages' were
one and the same. This came from having software distributed on a
medium with non-zero capacity (magnetic tape), and the presumption that
people would buy enough disk space to get the job done. The PC world
has matched this with CD-ROMS some years ago, but the PC applications
have been slow to take advantage of this. (Workstation applications,
such as Synopsis, Cadence, Interleaf, and FrameMaker have had their
manuals on-lines for years and years.)

It annoys me considerably that the PC guys (particularly Microsoft)
spend so much time stealing from each other, rather than stealing
from the real pioneers. Microsoft copied the Macintosh
when creating Windows, for example, rather than stealing the far cooler
stuff at Xerox/PARC and some of the workstation companies. And now
the Web has reinvented man pages, but forgotten equations (which were
part of the UNIX troff system by the end of the 1970's) and vector
graphics -- though of course they have cutesy-wutesy low-res color
bitmaps. (As someone pointed out, you can add plug-ins to add these
capabilities, which of course means that you're no longer running
standard HTML, and some of your readers will not be able to view
your files. HTML really ought to move briskly into the 1970s
and add all the blindingly obvious features into its next release.)

(I'm becoming less and less convinced that technology is moving at a
brisk pace. It's more of a drunkard's walk, involving a lot of
backtracking and falling face-down in the mud. It's just as PAINFUL
as brisk advancement, but the payoff seems lacking, somehow.)

-- 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: Gray Hairs
Next by Author: Re: To Laugh or Cry?
Previous by Thread: Re: Online Documentation. New! Improved
Next by Thread: Engineer Humor

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

Sponsored Ads