Online Help Help

[Rose Wilcox <RWILC -at- FAST -dot- DOT -dot- STATE -dot- AZ -dot- US>]

Lara Butterworth writes:

>Help!

>I've just been told that I need to put together on-line help for our next
>release of our software, UWI Masque, version 1.1, expected January 15.>

ROTFL.  "You want it *when*? is the first thought that occurred
when I read this.

>The software is on MS-Windows, Macintosh, X Window, and VM platforms.  Does
>anyone know the 'best' (read: fast and easy) way to do on-line help for
>any/all of these environments?  I know Windows has a help function, but I'm
>trying to seek alternatives to either (1) using Balloon help for the Mac
>(my boss says it's not hip enough); or (2) having ASCII text file dumps as
>an attempt at help for all environments.

The fast-and-easy way to create help in MS Windows is to use a tool
such as RoboHelp or Doc-to-Help or any of the plethora of other tools
available.  You would possibly want to do software evaluation before
deciding on your tool.  You *can* write MS Windows help in any word
processor that creates an RTF file.  You then must have access to the
Windows Developer's kit so you can compile.  Not having a tool gives
you a much greater learning curve time.

Unfortunately there is not one good way to have
on-line help that matches in functionality for all those different
platforms.
In fact, to *my* knowledge, there is *no* way to have matching help for
any *two* of those platforms.  If they have to
be the same, ASCII text dumps are going to be your best bet.

In terms of staffing, if you do use automated tools and you have to deliver
by January 15, I would suggest you need a writer full time per platform.
You will no doubt have a learning curve, and even with this level of
staffing,
you may find it impossible to make your date.

In addition, you will have a maintenance issue with a different tool per
platform.

>Any comments would be appreciated!  If you have experience with writing
>on-line help (I know its a different 'philosophy'), please pass this along,
>too.

If you are going with ASCII text dumps, it doesn't really matter, because
you are, in my opinion, not really "helping" your reader.  If you go with
automated tools, you need to write based on your tool to some extent.  For
example, with Doc-to-Help you can take your Word manual and have help
that matches your manual.  RoboHelp allows you to use the Windows
Help features more easily, so you can make a more customized type of Help,
using segment hyper-graphics with hotspots, for instance.  (Yeah, I know
you can do this is Doc-to-Help too, but Robohelp makes it easier.)

There is not room on this list to write a book about how on-line help
differs
from hard copy doc.  Go buy a book or two!  One good book for the Windows
environment which also gives good overall information about the differences
and roles of both types of doc is "Developing Online Help for Windows" by
Scott Boggan, David Farkas, and Joe Wellinske from SAMS Publishing.

>I'm only nine months into this career, and know very little (read: nothing)
>about writing on-line documentation.  Unfortunately, noone around here has
>either...

Good luck and have fun.  I love creating online help personally.  I suggest
you
talk to your management about the communication problems inherent in being
given a time-consuming task requiring upfront design and planning so late
in the life-cycle of your product.  If it's a Beta release, I suggest you
plan on
a later delivery of on-line help, depending on what you decide to do about
your tool problem.

Sorry I couldn't be more help (no pun intended).
Rosie
rwilc -at- fast -dot- dot -dot- state -dot- az -dot- us
ncrowe -at- primenet -dot- com

"The way to write is well, and how is your own business."
A.J. Leibling