Re: Online Documents (*Very* long post)

["Doug, Data Librarian at Ext 4225" <engstromdd -at- PHIBRED -dot- COM>]

<Humblest apologies to the list for an earlier, premature send of this
 post. I plead Monday after a long weekend, a long drive, and caffeine
 deprivation.>

This is in response to Paul's query:

**********************************
I would like to know how to learn to create ON LINE documents. It seems
that every add for Tech Writers is looking for that ability. Is there a
book or class I can take? Is there special software needed to write ON
LINE Help?
**********************************

Ok, let's begin at the beginning, with terminology.  On-line documentation
is a broad field, and encompasses everything from massive, hyper-linked
multimedia extravaganzas like Microsoft's CD-ROM encyclopedia to that
humble little line of ASCII text that appears at the bottom of a mainframe
screen when you try to exit without filling out all the required fields.

Although on-line documentation in one form or another is almost as old as
computing, we've only recently started paying close attention to it, and
some of the terminology is still a mess; take everything with a grain of
salt and realize other people may use different words for the same
concepts.

The oldest and simplest type of on-line documents are error messages and
status messages that appear in an application.  These are often imbedded
in the application code, and for that reason they are often written by
programmers. Some people don't consider them on-line documents at all.

On-line help usually means that a document is "bound" to a particular
application and can be accessed without leaving the application, usually
by using a "hot key," like the F1 standard in Windows applications.
"Context-sensitive on-line help" usually means that a particular part of
the help file will display, depending on what is happening in the
application.

On-line documents or references are usually "stand-alone" in the sense
that they don't require an application to either trigger them or to give
them meaning.  CD-ROM encyclopedias and references are probably the most
common examples, although the CD-ROM distribution medium is not essential.
ISO 9000, with its requirement that all procedures be available and
*current* has stimulated lots of development in this area.

Anyway, learning on-line documentation in general probably isn't a
practical goal.  Although there are some generally-applicable principles,
and writing online documentation is a separate skill from writing paper
documents, people will pay you to use tools and produce documents, not just
think helpful thoughts.  So, what you want to learn depends on what you
want to do.

At the moment, expertise in Microsoft Windows Help is probably the most
widely-marketable skill and produces the quickest results.  Ascendency of
another operating system or platform could change all this in a few years,
but at the moment it's the fastest, cheapest, and most widely-used path to
the online world.

Basically, the system consists of four parts: An RTF (Rich Text Format)
file that contains the text of the on-line document, an ASCII project file,
and a compiler.  The compiler uses the instructions in the project file and
converts the RTF file into a .HLP file.  The .HLP file can be displayed on
the screen by the Windows Help engine (WINHELP.EXE), which is shipped free
with every copy of Microsoft Windows.  Despite the name, WinHelp works
just as well for stand-alone references as it does for help files.

The cheapest way to get started (assuming you have a copy of WinWord) is to
scrounge a copy of the Help Compiler from an FTP site, The Windows SDK,
Access Distribution Kit, the Microsoft Developer's CD, or some other
development kit (I've heard Borland C++ is a good source). Hand-code the
markers into the document, save it as an .RTF file and compile it with your
Help Compiler.  You'll also need some sort of reference to WinHelp, (like
the Microsoft Help Authoring Guide) available from the same sources. If you
create a document of any size this way, you will understand WinHelp.  You
will hate it, but you'll understand it.

The next-cheapest thing to do is rummage around a little more on the
sources mentioned for the Help Compiler and find the WHAT*.DOT templates,
which slightly automate some of the more tedious aspects of coding an .RTF
document.  It's still a ticket to Maintenance Hell if the document is very
large and you have to make significant changes, but it is almost free.

To get some experience with a real WinHelp authoring tool, you have to
shell out a several hundred bucks.  The ones I'm most familiar with are
HelpBreeze, ForeHelp, Doc-to-Help and RoboHelp, although I'm sure there are
other excellent tools available.  With the exception of ForeHelp, most of
these tools are add-ons to Microsoft Word for Windows.  The office standard
is HelpBreeze, and I can send you the address, ordering information and
price lists privately if you are interested.

A little practice with one of these tools, guided by suggestions from the
Help Authoring Guide and other references, is probably the easiest and
cheapest way to get your feet wet in the online world.  There's also an
Internet list devoted to WinHelp.

If you are interested in non-WinHelp on-line technology such as SGML, I
would strongly consider tool-specific courses taught by vendors.

If you have bigger ambitions, such as interactive training applications,
you will need to decide what role you want to play.  Interactive
applications may require videographers, photographers, script writers,
coordinators, illustrators, instructional design specialists, programmers
and project coordinators.  Unless you have access to a *very* deep pocket
and this is considered a core competency for your company, it may be best
to bite the bullet and shell out hefty fees to contractors to do some of
the more multimedia-specific work (such as integrating the video and text)
while saving the scripting and instructional design issues for yourself.
If you are determined to learn about the multimedia aspects, consider
vendor-specific training.

Skoal,

Doug                            "Women are designed for long,
ENGSTROMDD -at- phibred -dot- com           miserable lives, whereas men are
                                 designed for short, violent ones."
                                  - Estelle Ramey