Re: paperless docs, minimal manuals

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

>How can you MASTER a program when you just have online help?

The people who publish the program have to take the "just" out of
"just online help."  Interleaf, for example, puts their entire manual
set on-line, with a hyperlink every entry in their exhaustive index.

>I want to read a manual and let it tell me all sorts of little things the
>program can do that never occurred to me.

You're describing a good manual.  Many software publishers do not
aspire to goodness in documentation.

>Using online help, if you don't ask the right questions, you'll never
>learn much but the most basic things the program does.

This is a lack of indexing.  I have a test for on-line help.  If
it has a real index, with at least two levels (and preferably) of
hierarchy, then the authors actually made an effort to make their
manual usable as a reference work.  If not, it's just a tutorial, and
should probably be ignored.  Reading on-line help is so slow, what
with the lack of indexing, sound-bite writing style, maze-of-twisty-
passages structure, and low-res display, that you're generally better
off not reading it at all.  It's quicker to figure things out by
trial and error, just as with Japanese stereo instructions.  (And
this from a guy who normally reads entire manual sets!  But on-line
help is too hard to wade through -- almost always.)

>I just got a new Mac with Clarisworks 2. something and a minimalist manual
>and I swear I will never voluntarily buy a Claris product.

>I tried using it, as I had to make a drawing, something I know nothing
>about, and the help system just looped me around and around.  And the
>manual just told me to go to the online help.

>Minimalist manuals are ridiculous,  and they  will make IDG publications rich.

"Minimalist documentation" is the art of telling the reader those things
he needs to know (that he doesn't already know), without burying him
in things he does know, unnecessary repitition, and massive examples.
The theory is that it takes more time to wade through the folderol than
it's worth, and that (with many audiences, anyway), the readers don't
want any hand-holding, they want to cut to the chase.

What you've run into isn't minimalist documentation, it's bad documentation.
Claris could provide a documentation set ten or a hundred times larger
than they did, and still be just as useless to you.  All they have to
do is screw up the cross-referencing and leave out crucial information --
two skills they have apparently already mastered.  Adding useless filler
into the bargain (assuming that it isn't there already) would require no
retraining of their staff, I'm sure.

        -- Robert
Robert Plamondon * Writer * robert -at- plamondon -dot- com * (408) 321-8771
4271 North First Street, #106 * San Jose * California * 95134-1215
  "Life is like an analogy."