Re: doc to help theory

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 05:06 PM 5/29/96 -0700, you wrote:
>Greetings and salutations!

Greetings and salutations right back at you!

>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.

Test it, long before you commit to it. As I recall, RoboHelp neither uses
nor recognizes master documents. If I remember correctly, it, like
Doc-to-Help, inserts its own fields for including subsidiary documents. If
so, you're sunk trying to use the master document feature.

>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. I'm pretty sure
Robohelp won't let you *hide* things when printing a manual, you must
convert to docs or help.

In order...it depends, and no it won't.

As in just about every other decision we make, professional and personal,
the decision to maintain two files is based wholly on your company's
priorities. If your top priority is the highest possible usability, then
you'll have to write, create, lay out, review, change, track and distribute
two different files. Yes, they have different needs. And yes, they would, in
an ideal world, be separately done. But be realistic...most companies don't
actually want utmost quality. They leaven that with concerns over speed and
cost. And in many cases, the priorities are reversed, so that speed and cost
become paramount and usability becomes no more than adequate. It's a fact of
life. Maintaining two files is horrendously expensive, in terms of writing
and creation resources, as well as the inevitable waste of one file's
reviewers catching errors that aren't caught in the other, and then which
file is right, leading to meetings, phone calls, call backs...and on and on.
The payment for the two-file system is a high one.

On the other hand, we developed DuoFrame (for FrameMaker, not for Word) to
answer the call for a minimally adequate help file that could be "calved"
from a single parent document once the parent is created, reviewed and ready
for print. The resultant help file doesn't have much in the way of
automatically-installed bells and whistles, but it works well enough to
satisfy the client. Word can be used the same way, but it's much, much
harder to do. Frame is set up to do such work, thanks to such features as
conditional text.

I'd look long and hard at priorities, and make management commit before you
launch on a two-file or a one-file strategy. Every aspect of the project
will be touched by that decision, so make it with wide-open eyes and a
signature from on high.

>I also want to make the help context sensitive, which I believe will be
even more difficult to maintain.

Oh, my, no, it won't make it all that hard to maintain. Even with relatively
large help files, comparatively few topics will actually be accessed from
your app, and you can readily get the context number list from your
programmers, which can be mapped in the hpj to the numbers you've assigned.

You write as though this might be your first biggie online/paper project. If
so, I'd heartily recommend Deaton-Zuback's book on Windows 95 help file
design. While it's ostensibly about Win95 in particular, the methodology
they include for design, layout and management is well worth reading for
help files on any base.



Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support

Makers of DuoFrame, giving you online help and paper
documentation from a single parent FrameMaker document.

http://www.iquest.net/simply/simplywritten

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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