Re: Online Documentation. New! Improved!

Subject: Re: Online Documentation. New! Improved!
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Thu, 17 Oct 1996 09:14:07 -0500


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

This describes printed documents also. Does the medium in which a
document is written cause these negative attributes? Is there no way
that fragmentary and redundant information can be avoided in online

>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

I've seen these problems in printed documentation also! What's your

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

I've seen many of these features. Most of my experience is with WinHelp
4.0, so I'll make comparisons to it.

Document feature ---> WinHelp feature

Flip through pages ---> Browse Sequence
Table of Contents ---> Contents Tab (and expandable/collapsible to
Index ---> Index Tab (and combinable with other on-line
????? ----> Search Tab
????? ----> Video files
????? ----> Audio Files
????? ----> Automatic executing and sequencing of
applications (great for tutorials)

>A top-level "topic list" replaces the table of contents and omits about 90%
>of the information.

What information is omitted? A written TOC lists the sequence of
chapters, subchapters, and procedures. An online TOC lists the sequence
of chapters, subchapters, and procedures (and with the ability to search
for a particular chapter by keying-in the starting letter(s) - some have
a contents search - some also allow you to search the TOC of related
on-line books)

>A search-by-keyword function omits virtually all of the utility of the index.

I don't agree. I use the find as a general search and the index as a
specific search. Typically, the find retrieves a larger catch.
However, I do find myself using the index instead of the TOC in many

>The document is a maze of twisty passages, so you can't even flip through it,
>it has no linear structure.

I've run out of thumbs many times trying to keep my spot in a written
document while chasing down cross-references. Here's a big on-line
advantage. Instead of nesting procedures or writing spaghetti
instructions (If ... then perform steps A-H, if ... then omit steps A-F
but perform G and H) the online document can display each of the
variations in separate windows. Furthermore, the user has the option of
displaying the pertinent procedure or to display them at all.
Therefore, as they become more familiar with the processes and just want
a refresher, they can quickly read the main procedure without reading
around all the If-Then branches or Refer-to-page side trips that are
hard to avoid in the printed document.

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

How about mentioning the things you can do with an online document that
you can't do with a printed document? Here's one.

Interactive tutorial. The online document automatically starts the
application for which you are learning. The overview and steps appear
in one window, the application in another. The instructions direct you
to perform some actions. After performing the actions, feedback as to
results can be returned (sometimes even analyzed). At this point, the
incorrect data could be highlighted, a hint button could be selected
that displays a pop-up error message and suggested solution , and the
user could have the option to correct the problems or continue to the
next step.

There could also be a Solution button. This button could display the
correctly completed process, guide you step-by-step (highlight each
step, verify input, and highlight next step), automate the application
to process the correct information (or show a video of the results of
the correctly completed step).

There could also be a Reset/Repeat button. This functionality would
allow you to repeat any previous step or forward to a particular step.
If the application needed preset information, it could be loaded
electronically into the application so that you could start from that
point. All this functions could be initiated from and synchronized to
the online document.

Let's see the printed document match this.

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

Are you talking online help or online books here? The purpose, IMO, of
online help is for quick reference. Typically, it's descriptions and
procedures are terse. That's its purpose. The user is looking for a
few pieces of information and wants to get to them quickly (and from
many different directions - index, TOC, find, or context-sensitivity).
They don't plan on reading the online help from front-to-back. Thus,
online help is not designed as a front-to-back document.

As per the 'rules du jour', online has many potentials that can liberate
it from the standard manual. It's also in its early stages. I see
nothing wrong with customizing it to compliment the application. It
should integrate as part of the application and not, necessarily, stand
rigid in its pre-computer era structure.

Online may not be a 'real' manual, but it is a 'real' document and its
acceptance/usage is growing 'real' fast.

Mike Wing

Previous by Author: Re: Senior Writer Job Requirements
Next by Author: Re: Online Documentation. New! Improved!
Previous by Thread: Re: Online Documentation. New! Improved!
Next by Thread: Re: Online Documentation. New! Improved!

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

Sponsored Ads

Sponsored Ads