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:Gretchen Toth <glt -at- ICONOVEX -dot- COM> Date:Thu, 30 May 1996 12:30:19 -0500
Hi Angela-
You wrote:
>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? I know Doc-2-Help tries to maintain Help and =
>doc from the same source, but it seems that the help would be very =
>limited. When I made my sample help file I had so many jumps and hot =
>spots, I couldn't imagine maintaining them within the same source as the =
>doc.
As a user, and a fan, of Doc-to-Help, I am reluctant to say I agree. I
really like the idea of single-sourcing, especially because you do not have
to edit errors/add new text/whatever twice. But the more I work with my
help files, and the more messages I see like Susan Gallagher's, the more I'm
convinced I need to change the way I design my help.
The approach I used in my last set of help files went something like this.
The hard-copy manual was arranged by procedures or tasks. A reference
section arranged by menu and dialogs followed. I converted the entire
manual to help, but arranged the task-oriented material and reference
material a bit differently. Instead of having these in separate sections, I
combined them:
* Intro material describing the task associated with the dialog
* 'Click Here' links to hot-spot dialogs
* 'How to'/task information
It took me quite a while to format the Word file just so I could get it to
convert to how I wanted it in the help, but I was able to use the same
source for both the manual and the help. And now that I put all the work
into it, I'm doubting whether the user really wants all that intro and task
information up front (as opposed to having field and dialog descriptions
first). And there's talk of moving all the reference material online.
:-)
Gretchen
<><><><><><><><><><><><><>
Gretchen L. Toth
Technical Writer
The Iconovex Corporation
gretchen -dot- toth -at- iconovex -dot- com http://www.iconovex.com
<><><><><><><><><><><><><>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
