Creating on-line docs: Summary

[Colleen Adams <PD33 -at- MEDISPAN -dot- COM>]

I received many requests to summarize the information I got
re: on-line documentation and how to get started.  So, for all you
techwhirlers who are interested, here goes (along with my
original posting--see "??s and Answers" for the responses I
received):  [I apologize in advance for this lengthy message...]

We are now getting more and more requests to provide our technical
documentation manuals on-line; however, I don't really know what to do
to get started.  Currently, all of our manuals are in Word95 (I know...
"aaarrgghh," "gasp," "yuck," you're saying to yourselves).

We have created on-line help for a couple of our Windows-based
products using Doc-To-Help, and I've received training on constructing
on-line documentation.  I have also budgeted for more training, tools, etc.
for this project in the coming fiscal year (so money is not really too big of
an issue)... BUT, I'm not really familiar with what tools are best, what
training is good, and the buzzwords associated with on-line docs.  HOW
DO I GET STARTED???

??s and Answers:
1) Is FrameMaker the way to go if converting some manuals to on-line?
A: For paper manuals to PDF? Absolutely!
A: If already using Word95, there is no need to convert.  You can use
Microsoft Help Compiler 4.0 (ships w/ SDK for any MS product) and edit
the RTF files the compiler uses in Word.  Just take the existing DOC files
and "save as" RTF.  You can then add tags.
A: Not necessarily, although I prefer FrameMaker over Word for manual
writing. FrameMaker makes it easier to produce Adobe Acrobat files
because it can covert cross-references to hypertext links and headings
to bookmarks.  The new version of FrameMaker (5.5) can save
FrameMaker files directly in Acrobat PDF format.  (website:
http://www.adobe.com/prodindex/framemaker/main.html
A: If you have docs written in Word or Frame, you can use Adobe
Acrobat to convert to PDF.  But you might want to convert to HTML
instead.  Frame may be coming out with a new version (5.2, 6.0?) that
includes a very good HTML converter.  If most of your customers do not
have Netscape or another browser, may want to consider using PDF
instead of HTML.
A: If you are throwing your current manuals on-line (and not creating
help), you could use Acrobat.

2) Is Word compatible with FrameMaker?  Is there a lot of work involved
in converting?
A: It's not bad once you get your Frame templates established. Word 2.0
and 6.0 are fine.  Word 97: no filters yet.  Frame 5.1.2 doesn't like the
RTF that Word produces.
A: It was awful! Converting takes a lot of time and cleanup.
A: You can import Word files directly into FrameMaker (haven't tried
exporting from FrameMaker to Word.)
A: Word and FrameMaker love each other! They're extremely compatible.
You can even preserve much formatting during the conversion.
However, don't know how to make graphics survive the conversion.
A: FrameMaker is a nice product for hardcopy docs, but the conversion
from Frame to online is not really easy.  Currently, we use Frame and
then convert the files to RTF to use in Word.

3) Has anyone used "Documentation Studio" by Wextech?
A: Only one person has used an evaluation copy.  Comments:  "it was
adequate, but I ended up creating my own tools using macros.
Doc-To-Help and RoboHelp are also not bad."  No other techwhirlers that
responded had tried this tool.

4) Is it best to code your own links or use an authoring tool?
A: I always recommend coding your own links.  It is relatively easy with
a couple of short cut keys.  Authoring tools take away a lot of power
and flexibility you have when doing it yourself.  As programs, they are
not "smart" enough to really understand some of the nuances you will
see.
A: I recommend choosing an authoring tool that makes it easy to make
links.  This is an advantage of FrameMaker:  As you created
cross-references, FrameMaker automatically converts them into
hypertext links when you produce an Acrobat file.
A: I can't imagine coding my own links.  I've always used RoboHelp
which I think is easy to use.  I say go with an authoring tool.  Less
hassle.
A: I like to code my own links since it gives me a better idea of the entire
structure of the help system.  This is really up to the author, each one
has their own ideas of how it should be done and what tools to use.
Another place to look is http://www.shareware.com.  Sometimes they
have useful tools that can aid you in building a help system.

5) Should you just say "screw it" and hire a consultant?  (consultants,
don't answer this one)
A: All responses overwhelmingly agreed that it is not necessary to hire a
consultant; however, it is a good idea to hire someone to do the work.

6) What are some of the averages in development time (per/page,
per/screen, etc.)
A: This depends on many factors:  resources, experience, complexity of
the material, etc.
A: 25 pages per day
A: 300 pages per day

7) Besides Dr. Gottfredson's course on "Constructing Online
Documentation" from SkillTech, what other training sessions are
worthwhile?
A: Anything by HelpUniversity (http://www.helpuniversity.com/) or
HyperTexas (http://hypertexas.com/)
A: Join the WinHelp mailing list.
A: Check out books by Bill Horton, "Designing and Writing Online
Documentation" (Don't quote me on the title)

8) Do you need to treat on-line manuals on CD differently from on-line
manuals sent via telecommunications?
A: You can put technical manuals on CD in PDF format (using Acrobat)
A: No. On-line manuals can be treated the same way regardless of how
you deliver them. But remember, you must specify that the user copy the
HLP and CNT files into the same directory; otherwise, they'll be looking at
all sorts of errors.
A: If you're planning to send online docs through communication lines
(esp. if your users have 28.8 modems), you'll want to make your online
docs as small as possible.  Try experimenting with graphic compression
options in Adobe Distiller.  If you distribute on CD, a network, or
high-speed data lines, you don't need to worry about file size as much.
You may want to look at limiting file sizes anyway to free disk space for
other purposes.

There's a lot of info to digest here... hope this helps some of you out
there.  It definitely helps me!  Thanks again for your quick response.

Colleen Adams
External Documentation Supervisor
Medi-Span, Inc.
Indianapolis, IN
colleen_adams -at- medispan -dot- com

 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