context-sensitive help and the printed manual

Subject: context-sensitive help and the printed manual
From: Alison Tartt <akt -at- att -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 21 Jun 2000 21:44:55 -0500

I'm struggling with an organizational problem in writing a printed manual
that will be the basis of the online HTML help (Frame files to HTML via
WWP). In writing the previous manuals for this product, there was no online
help, so the structure of the manual was totally task-driven (Creating
Customer Accounts, Updating Customer Accounts, etc.). Menus, screens, etc.
were explained only in the context of a task.

In designing the GUIs for this product, the programmers have put a Help
button on each dialog box, so I need to create help topics that will
display when the user clicks the Help button. These topics will explain the
purpose of the dialog and the various fields and buttons, input
requirements, etc.

Since I'm used to linear organization, I'm having trouble organizing the
manual to accommodate the context-sensitive material. Do I include the
procedure with the overview of the dialog box, or just create a jump
(online) or cross-ref (printed) to the procedural topic? And where do I
place all these topics about screens and dialogs in the printed manual?
Just after the related topic? (Unfortunately, some dialog boxes do more
than one thing.) Eventually I have to document every menu and command
within topics (there is no "What's This" help), and I'm also wondering
where that kind of material will appear in the printer manual.

I'm sure there are a number of organizational solutions that would work,
but I feel stumped. Any comments and suggestions would be appreciated from
those of you who have found a way to deal with these structural issues. I'd
also like to know if anyone has noted any mainstream product with good HTML
help that seems to balance task-driven documentation with program-driven
documentation.

TIA,
Alison Tartt




Previous by Author: FW: Outline Numbering in Word isn't resetting
Next by Author: Re: Insure vs Ensure, was Re: Should we hire this guy?
Previous by Thread: summary -- Indexing in Dreamweaver?
Next by Thread: RE: context-sensitive help and the printed manual


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


Sponsored Ads