TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: doc to help theory From:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Wed, 29 May 1996 19:23:09 -0700
At 05:06 PM 5/29/96 -0700, Angela wrote:
>We're working on a manual that we plan to convert to help very shortly, and after a bit of research I think we have the concept figured out.
>First we write the manual in Word 7 using the Masterdoc (is that a sin?) complete with toc and index. Next, we convert to help using Robohelp, which is really a one time event. We would follow up by making any changes in both the Help and Doc version at the same time.
>Because of the nature of the beast, the manual and help are two very different things and need to be maintained separately. Is this pretty much how everyone feels? [snip]
>I also want to make the help context sensitive, which I believe will be even more difficult to maintain.
>Are there any other feelings on this?
Well, Angela. You're on the right track, but...
First of all, steer clear of the master document feature in Word as it is
essentially worthless. Create each chapter as a separate document and create
a special "include" document that contains nothing but "RD" (reference
document) fields for each chapter. You'll use this "include" doc to access
each of the chapters and build the TOC and index.
Secondly, I'm glad you realize that paper and online are two separate
entities -- and I wonder why, then, you feel the need to take the entire
paper doc online *and* include context sensitive help. I find it's better
to plan the paper and online materials separately.
I'd advise that you plan your paper docs to include all the conceptual
information you want to include and complete task-based procedural
information. Leave out the contextual (field info) stuff. When you
document a procedure for the stamafragit dialog box, refer the reader
to the online help for field-related information.
Plan your online help from the other end of the overall picture. Start
with complete contextual information -- either to the dialog box or
field level, depending on your capabilities and ambitions. ;-) Then
include task-based procedural information as hyperlinks from the dialogs
on which the tasks are performed. Include the kind of brief, to-the-point
conceptual information the user needs to get up-and-running and no more.
Benefits of this approach are several -- A big one is that without
specific field information in the paper manual, it's easier to maintain
and can usually go to the printer while the code is still in final testing
stages. This gets the product into the box faster. Second bene is that you
plan the information to suit the delivery medium so you make fewer
compromises in the text. You can include all those transitional paragraphs
and tables in the paper docs and still provide the crisp and concise text
that online delivery demands.
Good luck with your project!
Sue Gallagher
sgallagher -at- expersoft -dot- com
-- The _Guide_ is definitive.
Reality is frequently inaccurate.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Post Message: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner: ejray -at- ionet -dot- net
