Re: Online documentation

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

 Lisa Hodge wrote:
 >We are currently in the early stages of planning our online doc
 >project.  We're looking for some feedback from those of you who have
 >already been through the process.

 >1.  Did you replace your paper doc or continue to provide paper doc
 >as a supplement to the online system?  If you still provide paper doc
 >to your users, is it a full-blown set or a condensed version?

Actually, most of the products I've documented had online help
from birth. The one that didn't was so huge (a development
environment) that online help was only a little piece of the
doc set.

I firmly believe that it's necessary to provide both paper and
online documentation for *most* of today's software products.
There are still very many people who refuse to use online help
or online docs -- either because the medium does not accomodate
their learning style or because they have been burned by poorly
written or poorly coded online systems.

When I design a doc set for a software package, I generally
put most of the conceptual info on paper and the contextual
info online -- the theory I subscribe to is that online is
for the "learning on demand" types and paper is for those
who take a more leisurly approach, wanting to get the overall
picture before they dive in.

Online documentation is a bit different from online help. You
can include more of the conceptual here. But the medium just
won't support a "dump" from paper to the screen. Online docs
that try to get away with that approach usually fail miserably.

I also hold the belief that including some tidbits on paper
that don't appear online is a way to frustrate software
pirates.

 >2.  Were your users receptive to the change to online doc?

Online help usually gets OK reviews from those who use it.
We're just about to embark on our first set of online docs
because of a change in marketing strategy (supplying multi-
user licensing and a single cd-rom or set of disks). A
single set of paper docs will also be included and additional
sets will be available for $. Since we haven't actually done
it yet, we'll have to see how it works.

 >3.  Did you provide the online information as part of the help system,
 >or did you convert the documentation so that it could be viewed online
 >(e.g., Adobe Acrobat)?  What tool did you use?

We'll be doing both. We'll use RoboHelp for online help (which will
include context sensitive and procedural info). Documentation will
be written in Word6 and used to single-source (with some massaging)
the paper docs (which will be layed out in Frame - probably) and
online docs (convert to .rtf and prepare using MS Multi-Media Viewer
Toolkit).

I expect a lot of other writers will question my choice of tools.
There reasons will be valid from the document writers point of view.
We could probably save some time by using a DTP/Viewer combination
such as those from Frame. But my usability studies have shown that
my target audience wants our products to look, act, feel, and taste
like MicroSoft products, so that's what I give them. Anything else
would introduce a frustration factor that could put us in a negative
light -- and that's the last thing I want.

 >4.  Did you hire a consultant, or were you brave enough to tackle the
 >project on your own?  If you did the work yourself, how much of a
 >learning curve did you encounter?  Any recommendations on training?

Learning curves will differ, of course, but I always recommend
against contracting out stuff like this. You're gonna have to
do it sometime. Why hire someone else to learn this and lose the
expertise when the project's over?

I recommend you take things a piece at a time. Work out a plan
to convert one "type" of documentation at a time to online.
Start with context sensitive and add to it until you gradually
have the system you want. It'll take time to do well.

Investigate the seminars that are available, do a lot of reading,
and look at every online help and online doc set that you can. Be
sensitive to the type of information you're looking for and how
easy it is to find. Criticize, analyze, plan, and attack. You'll
soon be an expert! You've already taken a great first step!

Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com