Re: Context-sensitive help and the printed manual?

[Geoff hart <ghart -at- attcanada -dot- ca>]

Alison Tartt is <<struggling with an organizational problem in writing a
printed manual that will be the basis of the online HTML help... In writing
the previous manuals for this product, there was no online help, so the
structure of the manual was totally task-driven... Since I'm used to linear
organization, I'm having trouble organizing the manual to accommodate the
context-sensitive material.>>

Don't change the linear structure of the manual. Although this structure
would seem to pose a problem when it comes time to generate the help, it
doesn't. When you compile a help file, the compiler generates a series of
Map IDs for the topics in the source file (or you create them yourself if
you're using an authoring tool that lets you do so). The order of these IDs
isn't important; all that's important is that you give them to the
programmers so that they know which ID goes with which dialog box.

The more serious problem is that online help does not use the same
conceptual structure or content that a printed user manual should use. In
general, users want the answer to specific problems with a given dialog box
when they hit the help key or click the help button; your manual almost
certainly doesn't structure information this way, since it's based on
tasks, not dialog boxes. One of the more useful means of dividing
information between online and on paper is to put context and instructional
information in print (where people can read it at their leisure) and put
primarily reference material online. (That's a simplistic breakdown, and
there are other useful approaches. But I've found thus far in my help
authoring career that the printed manual works best to teach people how to
use the software to accomplish tasks, and the online help to explain dialog
boxes and field-level help. So I generally reuse some of the information
from the printed manual, but reformat and rewrite it to account for the
different context of use.)

You'll have to spend some time figuring out just what you're trying to
accomplish with the online help (not just dumping a task-based manual
online) before you can really resolve your problem.

--Geoff Hart  @8^{)}    ghart -at- netcom -dot- ca

"Most business books are written by consultants and professors who haven't
spent much time in a cubicle. That's like writing a firsthand account of
the Donner party based on the fact that you've eaten beef jerky."--Scott
Adams, The Dilbert Principle