RE: context-sensitive help and the printed manual

["Smith, Martin" <martin -dot- smith -at- encorp -dot- com>]

I have been single-sourcing our printed and on-line documentation using
FrameMaker for some time now. I originally used WebWorks Publisher. Then I
wrote a set of scripts in FrameScript that eliminated the need for WebWorks
and better tailors the resulting HTML for our specific needs: Microsoft HTML
Help with context-sensitive hooks for Delphi applications and Dynamic HTML
web pages.

In either case, I add a non-printing chapter to the beginning of the manual.
Each heading in this chapter becomes its own topic in the help system and
corresponds with a specific screen in the software. This is where I include
the information that explains the purpose of the screen and any relevant
interface elements. I then include a list of cross references that link to
the procedural steps inside the manual.

Each heading in this chapter becomes the target of a context-sensitive link
in the software. However, I typically do not include this chapter in the
printed manual. The end result in the help system is something like:

Screen X
Screen X does such and such...
..............................
See *ABC* to configure the whatsit
See *XYZ* to configure the whosit

Where *ABC* and *XYZ* are hypertext jumps inside procedural sections of the
manual.

Hope this helps get the conversation going. I look forward to hearing more
about how other people handle this situation. Note that while, in an ideal
world, I would push for writing printed and on-line documentation
separately, doing so is not a viable option at this stage in our company's
evolution. Our Technical Writing Department, such as it is, currently
consists of 1.5 full time people.

Martin
Technical Writer / Audiophile
ENCORP: The Energy Automation Company