Re: Writing for on-line

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

        <snip>

> Readers may not read a printed manual from front to back, but the manual
> does have a "flow" that online does not have. For example, most readers
> expect to find the more general information before specific information,
> old before new, simple before advanced. They expect to find, in better
> manuals, an "overview" or "introduction" at the beginning of most
> chapters that covers the broader issues, with the "how-to" information
> grouped by category, function, etc. <snip>
>
> Also, with online, there is no concept of grouping categories unless you
> plan out your online topics to make use of the Browse buttons, although
> in fact (a fact I regret!) most of the new online help offerings seem to
> be eliminating Browse features altogether.
>
> Jane
>
I lost track here.  Are we comparing online help, online documents, or both
to the printed document?  If it is online help, I wouldn't expect to read it
from front-to-back.  Instead, I expect to press the "?" icon or F1 and get
immediate help on a particular item, command, gadget, or whatever.  IMO, the
user goes to online help for quick information.  "What does this control do,
again?", "How do I import a file?", "What are my data types?", and so forth
are some situations in which the user goes to online help.

In these situations, I want to spend as little time as needed in the
document.  I don't want an introduction or an overview to appear.  I also
don't want to hunt for the information or navigate a table of contents.  I
want to pop straight to the description and procedure.  This is something I
can do quickly online help but not so quickly with a printed document.  IMO,
the edge goes to online help for quick information.

For online documents, I have no argument that they do not read as well as
they do printed.  However, there are some compensations and some advantages
to producing the document online.  Some of these are as follows:

*       The document can be printed from the browser.  By using default HTML
formatting, the user can control the typeface and size of the text.  They
can view online in one font and print in another.  The formatting available
with HTML and web browsers is improving rapidly.  I can print a presentable
document through the browser that serves the need to read the document on
paper while maintaining enough formatting to keep it from looking like a
ransom note.

        If the user is printing from an online document, they probably
aren't as miffed by the restrictions in formatting as are we who write it.
They mainly want the information.  It seems to be the artist side more than
the communicator side of the writer that  wants the most aesthetically
pleasing printed document.

*       No print shop!  On line documents can be worked on up until
delivery.  Therefore, last minute changes are more easily incorporated.  For
example, another writer in my department is delivering a printed User's
guide and I am doing an on-line Programmer's guide for our application.
Because my document is online, I have three more weeks than she has to
finish the document.

        Also, if a mistake(s) is noticed after it is printed you're hosed.
However, with online, a couple of keystrokes corrects the problem(s).

*       No change pages or inflated ReadMe files to compensate for changes
that occurred after the copy went to the print shop.  Then there is the
expense of delivering a printed document as compared with the expense of
delivering one online.

*       Maintenance and updates.  Online documents can be changed and
e-mailed to clients.  I also am going add my documents to a corporate web
site.  It then becomes a living document.  Customers and partners can read
and/or download changed sections.  Furthermore, the can comment directly on
areas that are confusing, make suggestions, submit sample code and
work-arounds, and so forth.  There is now waiting for a reprint to get the
information.

*       Online help topics can be invoked from the online document.  I use a
help icon to indicate that online help is available for a command, option,
and so forth.  When the user selects the icon, the applicable WinHelp topic
displays.  This allows the user to read the workflow, overview, and
conceptual information in the online document and get detailed
reference/procedural information on demand.

*       Online documents can drive the software application.  Through
VBScript and JavaScript, controls can be placed to actually demonstrate how
to do something.  As a result, menus, commands, GUIs, and so forth can be
initiated through the document and executed in the application.  This is
often more comprehensive to the user than a series of static screen
captures, text, flow charts, and whatnot.

Topic grouping is possible (even can be enhanced) with online documents.  I
use a two-framed HTML page.  The left frame has a collapsible/expandable
TOC.  Selecting from the TOC automatically loads the applicable HTML file
into the right frame and advances the document (if necessary).  Furthermore,
the TOC entries highlight as the cursor moves over the TOC and the
applicable TOC entry highlights as the user traverses the document.
Therefore, the TOC automatically tracks the document.

Mike


Michael Wing (mailto:mjwing -at- ingr -dot- com)
Principal Technical Writer
Intergraph Corporation; Huntsville, Alabama
http://www.ingr.com/iss/products/mapping/

"Humpty was pushed!"