Re: Help or User Manual First?

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

At 07:35 AM 4/30/97 +0530, you wrote:
>Greetings from India!
>
>I have been asked to write a user manual and help for a banking
>application (PowerBuilder).  Normally, I feel the user manual
>should be written first and then the Help can be created by using
>the stuff from the user manual.  I am interested in knowing what
>is the best way to handle this situation. I am not familiar with
>RoboHelp or any such tool.  Here are some questions for which I
>require answers.
>
>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.
>
>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.
>
>I do feel that this is a chicken and egg question.  But as one
>Indian actor had responded: "To me at least the egg came first
>and then the chicken.  I had egg for breakfast and then had
>chicken for lunch."
>
>(I did search the archives but was not able to get the answer.)
>
>Thanks to all of you for being a part of this wonderful mailing
>list.  I look forward to any suggestions/tips that you can offer.
>I love being on this list!
>
>Best wishes.
>
>Guru
>
First, if you're going to do both in Word, you might want to go with
Doc-to-Help. IMNSHO, D2H is not top-notch, but it does have the minor virtue
of being intrinsically print and online capable at the same moment.

Second, I'm always loath to do both files together, because their universes
are entirely different. Hypertext requires a different thinking pattern.
We've created both together, of course, because logistic, planning, or
financial constraints often drive the bus. But when we do that, we come up
with a consistent structural pattern that will roughly serve for both. For
example, every chapter (and I mean EVERY chapter!) takes on a standard
template structure of discrete blocks: "How To...", "More About..." and so
forth. This structuring approach leaves little or no room for improvisation,
which can actually be a benefit under some circumstances.

As to the tool, we prefer FrameMaker for this kind of straddle operation. We
port the FM document as RTF and bring it into a third-party tool like
ForeHelp. FM has conditional text, which makes straddling much easier. We
have to be driven to use Word.

It's my feeling that the key to packing both files into one box is to
ruthlessly structure the document. Design your approach so that it works for
both, meaning that you'll have to compromise pretty heavily. There won't be
many popups, for example, unless you want to do them separately and lose
your time benefits of straddling. Then make each chapter conform to your
structure. In our case, for example, we started each chapter off with a
general "foyer" paragraph or two that became the entry topic for browsing.
It sets up the other paragraphs. Then in print, the next paragraph might
start out with the heading "More About...Printing a Page". That would become
a topic linked to the foyer topic and it would fill in details if the
reader/user wanted them.. The next print paragraph would be "How To...Print
a Page". That would become another linked topic that was solely a stepwise
procedure. This topic would be the context-sensitive topic to the
application, too. Field descriptions came in another paragraph, usually a
table, that started with "Field Descriptions..." and was (you guessed it!)
another topic linked to the foyer and to the "How To..." topic.

This structure made it easy to identify the various kinds of paragraphs and
gave us a design that would port to online in HLP, PDF, or just about
anything else. But it did involve great discipline and compromise.

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support
FrameMaker-to-HTML Conversions
HTML Help Consulting and Production

 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