Slapping it Online

[John Russell <JRussell -at- DATAWARE -dot- COM>]

The phrase "slapping it online" has also been duscussed in the guise of
"single-sourcing" (online *help* and hard copy. [Providing documentation
online--as opposed to online help--is still another side to the issue.])
 My company has been single-sourcing online help and hard copy out of
necessity for a few years.  We've become--perhaps unfortunately--quite
comfortable with doing this, and if I may say so we've become quite good
at it, too.

We've encountered two scenarios where "slapping it online" was
successful:

1) we've successfully single-sourced the documentation for a graphical
user interface (gui), supplying both a hard copy user's guide and the
interface's (Windows) online help from the same source files, and

2) we've successfully single-sourced the documentation for API type
information--an API for a proprietary scripting language, and an API for
a set of Visual Basic VBXs.

The most interesting thing about these two instances concerns the first,
the online help for the user interface and hard copy user's guide.  We
wrote the online help *first*, and then "reverse-engineered" the help
files into a 250 page, nicely chunked and task oriented user manual.
Very little, if any, rewriting was done.  The worst aspect of it was
that the online help was not organized or structured like a hard copy
manual--it was, not surprisingly, completely interface-centric (all the
commands listed under the File menu were in one file, under the Edit
menu were in another, under the Search menu in another, and so on.)
This, of course, had to be corrected.

The second instance was quite easy.  The VBX functions were nicely
chunked to begin with, and because API type information is typically
reference oriented, rather than task oriented, it fell right into place.


Now, whenever we approach a user interface of any type we write the hard
copy first, paying particular attention to these points:

*       making sure the document structure and the order of the topics within
that structure is sound
*       making sure the information/procedures in the topics are organized and
grouped by task (emphasizing one task/procedure per topic)
*       using graphics, but don't overuse them (no need for a graphic of a
system message when the only option the user has is to click "OK")
*       indexing judiciously (index entries become searchable keywords in
Windows online help files)


ALAS!  Isn't this how we would (should) approach strictly hard copy
anyhow???


The only real additional effort needed to single-source information is
to:

*       maintain two sets of formatting templates, one for the online display
and one for the hard copy.  (I would think that the debate over hard
copy presentation vs. online presentation of information should center
as much on the *formatting* of the information as anything else, and
this can easily be accommodated by the tools we use to produce both,
i.e. templates.)

*       create one or two additional "layers" above the hard copy to
accommodate interface-specific information.  (Single-sourcing online and
hard copy becomes increasingly difficult [on an order of magnitude, if
not impossible] for a poorly designed user interface.  You will more
likely be faced with having to describe features in an individual dialog
box that have nothing in common, which strikes at the heart of the
structure and task oriented nature of a hard copy manual--which, when
single-sourcing, is usually where you begin.)  To accommodate these
issues, we add the following "layers" to the help file:
        1) a top layer to serve as the Contents page (in Windows, the "Help |
Contents" screen typically gives the user access to a TOC, the
interface, the index, et.al.), and
        2) a layer of interface specific (or centric) information to account
for poor interface design.  In this way you can provide context
sensitive help from within a dialog box that contains six disparate
features by including a graphic with hotspots that point to topics that
discuss the task/procedure/feature.

In the end, we can take several hundred pages of hard-copy source and
transform it into an adequate and fully functional online help in about
a week.  AND, it saves my company money because each feature is
documented only once (as opposed to twice: once for online, once for
hard copy).

Cheers!

 --

kjr
jrussell -at- dataware -dot- com

K. John Russell                         Anagram of the year:
Dataware Technologies, Inc
5 Computer Drive South                  Information Superhighway
Albany, New York  12205                 New utopia? Horrifying Sham!