Help or User Manual First? -Reply

[Bill Sullivan <bsullivan -at- SMTPLINK -dot- DELTECPOWER -dot- COM>]

1.  Can one create the Help first in RoboHelp and then turn it into a
user manual? I would appreciate some broad guidelines and tips on how
to do this.  Specially, how to avoid any pitfalls.

It is possible to create the Help first in RoboHelp. RoboHelp comes
with an Export Documentation option to the Tools menu and a
ROBODOC.DOT template (for Word) that does some but not all of the
work. I assume you know that RoboHelp is not strictly speaking an
independent program but a little monkey that rides on the back of the
MS Word for Windows (version 7) elephant.  [I will probably hear from
RoboHelp about this!!]

I just made the first Export Documentation of my life, and it was
nice. It began with a RoboHelp dialog box where I set the thing up. I
chose my file to be converted and my target directory. I told RoboHelp
to convert graphics, make placeholders, check links to picture files,
strip hard page breaks, remove footnotes, remove hidden text, and
attach the robodoc.dot template.

It still left me with a lot of work. RoboHelp seems to have missed
all but one set of footnotes, but I got rid of them with a global
search and replace. I will want to strip out my jump text and a lot
of my context-sensitive text, the kind that pertains to buttons and
edit fields. Then there are formatting changes: Sans serif type in
online help to serif type in the manual; two levels of headlines
online against four or five in the manual. But the big chore will be
organization. To make a long story short, I don't organize my help
files the way I would organize a book. That is the nature of the two
beasts.

2. Or should I write the user manual first in Word and then turn that
into Help files?  Here too, any tips and suggestions would be welcome.

It's possible. It depends on how you envision your Help program. If
access will be from the Help menu only, and you envision your Help
program as an online version of your user manual, then it probably
doesn't matter. RoboHelp  will handle the conversion for you as will
most major help tools.

If access will be context-sensitive so users can press F1 at the
various dialog boxes and menus within the program and get the help
topic for that dialog box or menu, then it probably doesn't matter
either.

Tim Altom hits a very important nail on the head when he says:
"Hypertext requires a different thinking pattern."  Manuals are about
the program and are written from beginning to end, starting with an
introduction, then how to install it, how to operate it, and
amplification in the form of appendices. With context-sensitive help,
you write a lot of little stories, each about a different dialog box
or menu.

There are other options that you haven't mentioned. You could develop
a context-sensitive Help program and you could take the sections and
subsections of your manual and convert them into a second Help
program called Mymanual.hlp. If you are developing help for Windows
95 or Windows NT, you could then add a menu option or menu item to
your context-sensitive program so users could access the entire
manual if they wanted.

You could also convert your manual to html and put it on your web
site. Or you could convert it to a .eps file and send it out with the
Acrobat Reader -- if distribution will be via CD, the Internet, or a
server.

By the way, we are talking Windows 95 and Windows NT here, aren't we?
If you are thinking Windows 3.1x, OS/2, or some flavor of Unix or the
Macintosh, that will change things either a little or a lot.

I assume you know there is also a Winhelp listserv. You might also
get some useful information by checking Cherie Zubak's WorkWrite web
page (http://www.workwrite.com) and Mary Deaton's Knowware page
(http://www.kware.com).

>I do feel that this is a chicken and egg question.

I see it more as a plate full of curry surrounded by condiments
question. Do you first put onto your fork some rice and some lamb and
a few peanuts and chutney, or do you mix the peanuts, the chutney and
the coconut into everything? Does it matter? You are going to eat it
all anyway, are you not?

Bon appetit!

Bill Sullivan
bsullivan -at- deltecpower -dot- com
San Diego, California

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html