Re: Creating on-line docs: Summary

["jack w. bonney" <ssi_can -at- ISTAR -dot- CA>]

Colleen Adams wrote:
>
> 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
one last thought connected to my previous message to you....

if you have several (3 or more) topics that will have to be maintained,
you should consider whether you will need some paper-based copies; if
you will need paper-based copies, then do you need office-size and
handbook-size as well.

we have found, that out of all the paper once produced on manuals (i.e.
all the field copies) you will only be able to eliminate about 60% of
the paper....

this presents another challenge: how to syncopate the revisions so that
everybody is reading out of the same version at the same time???

when the master version is ready for release it is ready for instant
access across your network, however, if it will take several days to a
week or longer to produce the paper-based updates, then you will have a
problem...

some subtle issue to consider, all of which we have addressed and
solved.

i hope this information is helpful....

sincerely,

jack w. bonney
vancouver canada

 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