An: "Ideal" help system

[Dan Emory <danemory@xxxxxxxxxxxx>]

These are the features and structure that I believe constitutes
an ideal help system

INFORMATION HIDING
The concept of information hiding (also known as details on demand) provides
an effective way to condense information. Links give the user the option
of selectively getting more detailed information about things that are
mentioned in the condensed text.

EXPLORATION NODES
Another technique I strongly favor is the use of what I call exploration
nodes. An exploration node (often in the form of a graphic, list, or tabular
array that is replete with links) provides the user with a bird's-eye view of
a particular subject area or content type. Exploration nodes provide the
user with "base camps" for conducting exploratory probes within a subject
area. After each probe, the user can jump directly back to the base camp
and make another exploratory probe down a different path. Exploration
nodes also help users to form mental models of the knowledge base.

The top-most page (Top of Help) in the on-line help structure should always be
an exploration node.

The first page of each section of the on-line help should also be an
exploration node, in the form of a hypertexted local Table of Contents.

OTHER NAVIGATION AIDS
Each page within each section should have a navigation bar that allows the 
reader to
jump to the following points:

+ The first page (containing the hypertexted Table of Contents) of the 
section in which that
page resides.

+ The Top of Help, which allows the reader to navigate to the first page of
any other section.

The Details on Demand links, Exploration Nodes, and Navigation Aids
assure that there are no navigational cul-de-sacs within
the on-line help. Thus, if the reader navigates to an unhelpful help page,
(s)he can always recover and re-navigate to another more promising point
in the help structure.

Usually, I create six major sections in the on-line help.

SECTION 1
The first section is the Top of Help. It includes an exploration node in 
the form
of a diagrammatic representation of the on-line help structure.
The diagram includes hypertext links that take the reader to the first page 
of each
major section.

SECTION 2
The second section contains highly structured, task-oriented, narrative 
overview
text that is replete with hypertext links to relevant nodes in the other 
sections.

SECTION 3
The third section is based on Human Engineering findings that adults think 
in terms of
Action-Object-Method. That is, they say to themselves:

"I want to perform this action (e.g., Delete, Add, Insert) on this
selected object (e.g., a data type), and I want to know which
method (i.e., task or procedure) accomplishes it."

Consequently, the third section contains Action-Object-Method tables,
which are 3-column tables, with column headings of Action, Object,
and Method. Two or more such tables are used when action types
can be logically subdivided into major task groups.
Often in these tables each listed Action is a vertical straddle of two
or more rows, and the second column has two or more unstraddled rows,
with each row identifying a particular object type upon which the action
described in the first column can be taken. If there are two or more object 
types which use
the same method, the Method column is also a vertical straddle of
two or more rows. For simple actions, the Method column describes
the actual procedure (e.g., "Choose File > Import > Formats to open
the Import Formats dialog"), where clicking on 'Import Formats' produces a 
hypertext
jump to a description of the Import Formats dialog box.
For more complex tasks, the Method column has a text
string such as "See Taskname for details", where clicking on Taskname 
produces a
hypertext jump to the applicable task description and/or
procedure. within the Task section (section 4). In effect,
the entire third section is one massive exploration node.

SECTION 4
The fourth section contains the task details, mainly for
complex tasks that are not fully detailed in Section 3.
This section is also highly structured so as to organize
tasks into logical groupings. For each logical grouping, an Exploration
node should be provided. Each task description begins with an
overview that describes the purpose of the task, and any caveats/explanations
that may be required. The task descriptions are also replete with
hypertext links to relevant nodes in sections 2, 3, and 5.

SECTION 5
The fifth section contains the descriptions of individual dialog boxes.
Here again, the information is highly structured. The dialog box
descriptions are logically grouped. When clicking on buttons in a
main dialog box takes the reader to subordinate dialog boxes, those
subordinate dialogs are grouped with the main dialog, and a
graphic may be included within this grouping to show the relationships
between the main and subordinate dialogs. This section
is also replete with hypertext links to nodes in the second and fourth 
sections.
Section 5 also provides the source of context-sensitive help when
a user has a particular dialog box open, and requests help on it from within
the software application itself. (e.g., by hitting the F1 key).

SECTION 6
The sixth section is a glossary of terms. One of the things that drives users
to distraction is the use of jargonized names for things and actions, as 
well as
the use of technical terms that may not be understood by many users.
Each term should have a brief definition. If there are locations in the 
help structure
where a name/technical term is explained more fully, or where examples of 
its usage would
help the reader to understand the meaning, hypertext links to those locations
should be included in the definition.

SUMMARY
The whole purpose of the on-line help structure described above is based on the
recognition that no author of on-line help can anticipate how diverse users 
will
attempt to find help in the myriad situations where help is needed. With
the structure described above, the user can start almost anywhere in the 
structure, and
can always navigate quickly and successfully to the particular nugget that 
solves his/her
problem of the moment. Many on-line help documents seem to be designed 
almost solely
to assist highly clueless new users in getting started. In most cases, 
however, they
not only fail at that, they also fail utterly to provide useful help to 
more experienced
users. The structure I've described serves the clueless and the power user 
equally well.




====================
| 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
177 Riverside Ave., STE F, #1151, Newport Beach, CA 92663
---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.   **