Re: paperless docs, minimal manuals

[Bonni Graham <bonnig -at- IX -dot- NETCOM -dot- COM>]

OK, OK. I was, in the interest of conserving my time, going to stay relatively
out of the online-vs-paper discussion, but I have to jump in and say a couple
of things.

Robert Plamondon wrote:

><snip>  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.

I don't think it's fair to blame the authors for this.  WinHelp really only
allows you one level of indexing, which turns the procedure from indexing to
keywording.  What is fair to expect WinHelp authors to know is the art of
keywording.  Anyone who's worked in a library or with keyworded abstracts knows
that indexing and keywording are different skills and must be approached with a
little different thought process.

You don't get a hierarchy, you get a single entry point, so you must think
about your information a little differently (e.g., making sure your topic title
is specific enough that users can select it confidently after reaching a title
list via keywords and that your topic is specific enough that it contains the
information they wanted once they get there).

Also, it's often a bad idea to put length procedures in online help anyway, for
the reasons Robert cites below.

>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.)

This one we can safely blame the authors for, and not the technology.  Reading
BAD online help is slow.  Reading well-designed online help isn't any slower
that reading the book (and if the topics are properly titled and keyworded, it
can be much faster).  If you're dealing with a "maze of twisty passages" help,
you're dealing with someone who couldn't be bothered to design the help
structure carefully. This is not the fault of online help itself.

Also, it can be hard to figure out what to put online and what to put on paper.
You really, generally, DON'T want exactly the same information in both places.
You may want variations of the same information in both places, depending on
the type of doc set you're designing.  I presented a paper on this at the
Sacramento Writer in the Workplace Conference and at the San Diego STC March
chapter meeting.  I can send a copy of the paper to anyone interested, and we
taped the meeting, so a copy of that is available for loan or purchase to
interested parties as well.

If you try to figure things out by trial and error in, say, a client-server
database application, you may end up frying your company's data.  *I* wouldn't
take that risk.  If it's just my own stuff, I'll play all I want, though.  I'll
still check the onlie help or manual to see if I'm doing it the hard way...and
I have, oh, I have.

>What you've run into isn't minimalist documentation, it's bad documentation.

This I agree with absolutely, as I mentioned in an earlier post.

I'd like to mention that I don't intend this post as a flame of Robert.  I
wrote because I noticed some assumptions that I found to be faulty in his post.
I may have misread what he meant.

Bonni Graham
Manual Labour