Some Thoughts about On-Line Help

[Dan Emory <danemory@xxxxxxxxxxxx>]

Recently, there have been a number of posts with opinions about on-line help
and how it should be implemented. Here are some of my thoughts on the
subject, based on more than 10 years experience in developing
context-sensitive on-line help.

1. Most software vendors today are using on-line help as a substitute for,
rather than an adjunct to, complete documentation in printed form. The FM
V5.5.x documentation is a perfect example: Both the on-line help and the
printed documentation are lousy and incomplete. Also, the 500-page FM+SGML
Developer's Guide is a prime example of something that should have never
been provided as an on-line help document. You simply can't effectively use
that document unless it is first printed--an onerous task that users
shouldn't have to perform.

2. An  extreme example of what happens when all of the information is in
on-line form is Adobe's documentation of the Acrobat product line. It's very
poorly done. When you're lucky enough to locate the procedure you're looking
for, you can't perform the procedural steps on the document of interest
while simultaneously reading the on-line help. Anyone who believes the
Acrobat on-line help is adequate, must explain why one of the most dominant
subjects on the two Framers lists relates to problems with PDF. To
paraphrase what Conrad Taylor pointed out in one of his posts, "PDF is
rocket science, and very poorly documented rocket science at that."

3. Anyone who prefers reading complex technical information on a screen
rather than in a printed manual is severely twisted. 

4. Here are some vital things you can do with complete printed documentation
that you can't do with typical on-line help systems:
	a. Annotate it.
	b. Read back and forth between the two facing pages where the book
	    is currently open.
	c. Put two or more of your fingers at relevant places in the book, and
	    rapidly flip back-and-forth between those locations, allowing up to
	    6 or 8 pages to be examined almost simultaneously.
	d. Read a procedure and actually perform it step-by-step while you're
	    reading it.
	e. Conduct, away from the computer, a  planning or problem-solving
	    session in  which all attendees have a copy of the printed manual.
	f. Other than FrameViewer and Acrobat, few, if any on-line help
	    systems are capable of replicating the kinds of complex page
            layouts, tabular arrays, high-resolution graphics, and
            rich formatting that are possible in printed books. This detracts
            from readability, and from the ability to rapidly scan through the
            text in search of the needed information.
	g. Only FrameViewer and Acrobat offer the capability to zoom in
	    so as to more closely examine small-sized text and large, complex
	    graphics.

5. Hypertext link types available in most on-line help systems are not
robust enough to do the job. Although FrameMaker's hypertext toolkit is
quite robust (e.g., cross-reference links, newlink/gotolink, gotopage,
openlink, openpage, popup menus that allow users to select the destination
they want, matrixes, alert popups, Previous/Next Page, Previous Link,
message), most of these links do not convert in on-line help systems other
than FrameViewer, which Adobe is in the process of phasing out.

6. Designing a context-sensitive on-line help system that also provides
robust navigation capabilities once a help document is opened is a highly
demanding and creative task that requires special talent.  Here are some
quotations  that make this point clear:

"...(Authors must) structure the hypertext so that it corresponds to the
ways that readers might think about the topics, and to help readers create
the appropriate mental models of the knowledge base...The ease with which
readers use and comprehend hypertexts, and even their ability to locate
information, depend upon the structure of the hypertext network..."
- Schneiderman, 1991 -

"Success or failure of a hypertext product depends on how well the developer
deploys links."
- Davison, 1989 -

I've been designing (off and on) hypertext documents since the 1980s, long
before the advent of the Web. Most on-line help products I've evaluated
don't even approach adequacy, much less proficiency. Most people who design
on-line help systems think they can anticipate how the reader will think,
and deploy the links accordingly. They're wrong.

Here is how adult readers think:

+ Adults are thrown into action; they can only understand through the
effectiveness of their own actions in the world.

+ People are in a world more real to them than a series of steps, a world
that provides rich context and convention for everything they do.

+ People are always trying to find things out, thinking things through,
relating what they already know to what is going on, recovering from errors.
They're too busy learning to rigorously follow step-by-step procedures.

+ Adults are impatient learners; they want to get started quickly on
something productive. They skip around in manuals, and rarely read them
fully. They make mistakes, but learn most effectively by correcting them.
They're best motivated by self-initiated exploration.

The reality is that every reader thinks differently, and his/her thinking
process adapts to the particular problem (s)he's trying to solve. It's
impossible for on-line help designers to anticipate all of the permutations
in the way different readers will think in different situations. The
solution to this dilemma, as Schneiderman points out, is to provide the
reader with a carefully developed  mental model of how the knowledge base is
constructed, and deploy, as Davison suggests, the profusion of links and
navigational aids required to fully implement that model. 

That includes eliminating navigational cul-de-sacs. Readers of on-line help
do the same thing that readers of printed manuals do. When searching for the
information they need, they typically hit dead-ends, or the need for a
subject jump, either of which requires them to proceed down other search
paths until they (eventually) find everything they're looking for. That's
fairly easy to do in a printed book, but a navigational cul-de-sac in an
on-line document prevents the reader from recovering.

Consequently, each page of an on-line help document must provide the
navigational aids that allow the reader to always select another search
path. This is best done by providing, on each page, a navigation bar
consisting of buttons, where each button represents a basic type of
navigation option (e.g., Global, Local, Previous Link, First/Next/Previous
Page). Clicking on the Global or Local button  produces a popup menu listing
destination options in that category.

For example, clicking the Global button might produce a popup menu with the
following destination options:
	Top of Help (a hypertexted pictorial representation of the knowledge 
	base model)
	Help on Help (explains how to use, and navigate in, the on-line help)
	List of Major Sections 
	A Global Table of Contents
	A Global List of Tables
	A Global List of Figures
	Index
	Glossary
	Synopses of major subjects (helps the reader to determine whether
        (s)he should go further down that path)

Clicking the Local button produces a popup menu listing destinations in the
same category as the currently displayed subject. The first page of each
on-line help module should include a hypertexted local Table of Contents.
The Local navigation button, among other things, provides the option to jump
back to that first page so as to go to another (related) topic within the
same module.

In context-sensitive on-line help systems, it is unwise, therefore, to
produce a separate module (i.e., file) for each context-sensitive link.
Rather, a module should consist of an entire functional category. Initiating
a particular context-sensitive request opens the help module, and displays
the relevant page. However, in complex products, there's a good likelihood
that the reason the user has requested help is that (s)he's using the wrong
tool (e.g., dialog box) to carry out the desired task. Upon discovering this
fact by reading the text for that tool, the user can quickly recover by
jumping to the first page of the module, where the local Table of Contents
will indicate all of the possible alternative tools that might accomplish
the task, or which are
needed in combination with the origianal tool to fully carry out the task.

9. Here is a summary of some important on-line help design criteria:

+ The retrieval delay between a user-initiated help request and the
appearance of the requested information should not exceed 8-15 seconds on
the worst-case platform/server combination, and ordinarily should be well
below 10 seconds.

+ The file structure, organization, and navigational aids must facilitate
navigational efficiency. Here are several quantitative indicators of efficiency:

	- It deteriorates when the number of mouse clicks required to move from
	   one subject node to any other subject node in the knowledge base
	   exceeds 3.

	- It deteriorates as the number of intermediate documents that must be
	   traversed while moving from one subject node to any other subject
           node in the knowledge base increases.

	- It deteriorates as the number of navigational cul de sacs increases
	  (a node that is a cul de sac provides no way to jump to another
          level).

	- It improves as the number of exploration nodes increases.
	   (An exploration  node is one which provides (pictrorially,
           in a table, or some other way) the hypertext links needed
           for a reader to throughly explore a particular subject area,
           returning, after each probe, to the exploration node to
           conduct the next probe).

+ Documents must be designed to facilitate both on-screen readability and
rapid access to the particular information a user seeks:

	- The number of nodes that are one page or less should be maximized;
	  the number of nodes that exceed two pages should be minimized. 
	  Applying the concept of information hiding (i.e., details on demand)
	  is the best way to achieve these goals.

	- The worst-case combination of monitor size, resolution, and display
	  quality usually dictates minimum font sizes and maximum page size.

	- Serif-less fonts (e.g., Helvetica) are easier to read on a screen than
	  serifed fonts (e.g., Times)

	- Visual cues (e.g., color, font changes, boxed text, tabular
          arrays and bulleted lists) help readers to rapidly locate
          information.

	- A landscaped page makes more efficient use of screen space.

Let the Flames Begin!

     ____________________
     | Nullius in Verba |
     ********************
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory@primenet.com
10044 Adams Ave. #208, Huntington Beach, CA 92646
---Subscribe to the "Free Framers" list by sending a message to
   majordomo@omsys.com with "subscribe framers" (no quotes) in the body.


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **