Creating Online Help

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

You didn't say what format the existing manuals are in, but I suspect that
your first efforts at online in this environment will be something you
won't want to boast about in the coming years. You're probably attempting
too much too soon to make it all work neatly and useably, especially if the
existing manuals are, as I suspect, in something like Word. You're going to
have to overhaul the printed versions extensively to get them in a decent
online shape. This is time consuming. And if you're just learning the
online world at the same time...well, let's just say I don't envy you.

>I'm considering suggesting the following timeline:
>
>1. Ship online documentation with GA, end-of-January 1998.
>
>2. Create an online help system using RoboHELP for beta shipments
>   end-of-April 1998.

I'd consider a faster tool, HyperHelp or ForeHelp. I wouldn't use RoboHelp
for anything that required maximum efficiency.

>Here are my questions:
>
>1. Has anyone used FrameReader to provide online books? What effort
>   was involved in providing them this way, as opposed to hardcopy.

Are your originals in Frame? That changes the picture considerably. But I
wouldn't even consider using FrameReader nowadays for external releases.
It's cheap and simple, but not terribly usable or portable. I'd use
Acrobat's PDF.

>2. What's your favorite way to provide online books? How much effort?

Again, if I have to, I'd supply PDF. Effort is proportional to usability.
Just slamming a PDF from Frame is simplicity itself. It takes longer to
load the software than to PDF the Bible. But then installing links and
making it do tricks will take mucho time. Just doing bookmarks and/or
thumbnails is quick.

>3. How long does it take to put together an online help system for
>   a fairly large software program. Do you think it's too ambitious
>   to try to ramp up on help authoring tools, put the system
>   together, and put out a major revision of a doc set in three
>   months?

In order: a)months, unless you're using a parent document, b)yes, by a wide
margin. But these answers assume that you want the online files to be truly
online help, not just electronic versions of what you have in print. If
you're using FrameMaker, look at its online help. Not terribly useful.
That's about what you'll get with FrameReader. Simple, but not elegant. Try
Microsoft's online help, especially in 95 or NT. That's pretty good stuff,
context sensitive to a fault and well-honed.

My suggestions would be:

First, try to get your deadline extended. In three months you can probably
get something out, but it probably won't be your best work. Then second,
review your print doc, both existing and what you plan to do, with a bold
eye for what sections would make good online topics and which won't need to
go in. If necessary, restructure ruthlessly so that you're consistent
throughout. Then third, set up a good template in whatever tool you're
using to tag each "break" for the topic...presumably headings. This will
come through into RTF and let you more quickly split the file into topics.
If possible, as in Frame, create conditional tags for "print only" and
"online only".

Then, having planned this out, you can use this print version as a "parent"
and you use the print development time to bone up on a help tool and and
the principles behind help. I'd recommend ForeHelp. With it you can
"inhale" an RTF straight out of Word or Frame and if the headings are
properly tagged, as they should always be, you'll get a help file properly
sliced into topics. All you'll have to do is install your jumps.

This way you write, review, and finalize only one set of information
"segments". These then become topics at the push of a button. This will
shorten your development cycle considerably.

There are, of course, lots of other details to work out, but we've found
this system to be extremely helpful.

Best of luck to you.


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

	http://www.documentation.com/, or http://www.dejanews.com/