On-line vs. print (WAS: Of myth and reality)?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Eric Dunn wondered: <<I often hear the... phrase "online help and printed
documentation have entirely different requirements". Is this really true, or
is it just a myth that serves as simple termination to discussion of
studying more efficient ways of delivering information to the users?>>

"Entirely different" is certainly a myth, though it's often used as
convenient shorthand for "you can't just dump printed manuals online". None
of these differences prevent single-sourcing, but each of them does have
implications for how you tweak the message for the new medium. Sure, the
steps in a procedure are identical whether you describe that procedure in
print or online, but the devil's in the details.

<<While information is presented in a different format in online help and
printed documentation, this is simply a difference in templates. I do not
consider any point concerning colour, page size, fonts, or anything else
touching templates as a validation of the phrase above.>>

Templates are certainly an issue; I won't even bother trying to read a
manual dumped online as 8.5x11 inches and called "online help". I consider
that unusable and insulting. Once you exclude the factors related to the
presentation medium (e.g., page size, color, font legibility), you can still
have significant differences. These include:

Hierarchy and Sequence
-------------------------
Print documents are organized around chapters, sections, and subsections,
and well-designed documents clearly display this hierarchy. The goal of the
hierarchy is not just "template" related: it provides context for a given
section or subsection and thus, reveals how that chunk of information fits
in with the surrounding body of information. Perhaps this isn't
theoretically necessary, but its something we old farts grew up with and
became proficient at using. Maybe younger, more highly evolved generations
will find this unnecessary. <g>

Online help conceals hierarchy on the assumption that readers only want to
see help related to the current screen, dialog box, or field. This has the
advantage that you can exclude irrelevant information (thus making it easier
to find the relevant information at a glance without so much skimming), and
the disadvantage that it hides relevant information readers might need to
encounter before encountering the current chunk. Hyperlinking doesn't solve
this problem because as soon as you define the chunk size (e.g., a single
help topic), you define what context is visible. In print, readers can "zoom
out" to their heart's content to see increasingly broader contexts without
ever losing sight of the current chunk. You can't do that yet online.

Contents
---------
Print documents, however they're organized, offer a clear linear sequence;
someone sat down and said "read the information in this order". Browse
sequences emulate this approach, but many users never recognize that this
sequence exists unless you beat them over the head with "click here to move
to the next topic in the sequence" messages. In print, readers see the
previous paragraph, page, subsection, section, or chapter at a glance, and
know that what comes before provides introductory information that explains
the current topic and that what follows builds on it. So in effect, online
information requires explicit clues to structures that we accept implicitly
in print, and those clues are an important difference from printed
documentation.

Here's another example. If you open a book, you see at a glance that there
are several topics on a two-page spread, and that sends a clear message:
"there's more text than just this first heading, and here's what that text
is [indicated by the headings]" If there are no subheadings, that's
information too: "this is a long topic and you'll have to turn the page to
see what, if anything, follows it." In online help, a tiny window opens with
an elevator (scroll) bar: you know the topic is longer than a single window,
but have no idea what subtopics exist several screens later. This forces you
to skim. Why not do what I do, and add a mini table of contents at the top
of the topic, with hyperlinks to each of the subtopics? This presents the
structure of the current topic at a glance and provides easy one-click
access to the subtopics. Yet as repeated discussions on techwr-l show,
including these mini-TOCs in printed manuals is considered a waste of space.

Assumptions about what's been read
-------------------------------------
When you make the decision to chunk text for online use, you are consciously
choosing to exclude information so that the topic displayed in the help
window focuses narrowly on the current context (a field, dialog box, or
screen). By definition, this puts control over the content of a topic in
your hands, not the reader's hands. In print, you let the reader make this
decision; if they look up a keyword in the index and find the desired narrow
topic (e.g., one paragraph), they know that the surrounding text contains
information that explains the current topic or builds upon it. Better still,
if the current paragraph doesn't provide enough information, they can simply
flip back until they find the heading that begins this section, and start
reading from that point. Browse sequences can fake this, but usually aren't
designed to do so. Plus, some folks simply don't know that they're there.

Screenshots
------------
Obviously, printed manuals must use screenshots judiciously to direct reader
attention to the desired parts of the screen. In online help, the screen is
there all the time, hidden beneath the help window, so using screenshots is
often a waste of time. At best, it's a poor choice, given that existing
technologies such as Apple's Guide and Microsoft's wizards should let you
interactively highlight the relevant elements of graphics as you work
through each step in a procedure. Printed manuals can only fake this (e.g.,
by sequential screenshots), and you can't build interactivity into print the
way you can (and should) online. This means that if you write a print manual
and simply dump it online, even with a good template, you're ignoring the
main reason for putting the information online: to make things easy.

This leads into the larger problem of how to arrange help files so that they
don't obscure the interface. Printed manuals can't obscure the software
unless you physically staple them to the monitor <g>, thus you can display
screenshots at 100% (or at least at full-page width). You can't generally do
this online without concealing the software. Conversely, online graphics
should ideally be scalable objects, not bitmaps, so viewers can zoom in on
them until they obtain the desired level of detail. I don't recall seeing
this approach, but it offers power you simply can't provide with graphics
designed for print. Why don't we use that power?

Embedding help
----------------
Online help systems offer a possibility you simply can't do in print: they
let you tie the help so closely to the interface that the user never knows
they're using a help system. Compare, for example, the difference between a
field labeled "Name (use only letters)" and the print equivalent: "in this
field (big arrow pointing at screenshot), use only letters" or "in the field
labeled Name, use only letters". Trivial example, but the point is clear:
the online version doesn't require any documentation because it's
self-documenting. This introduces a fundamental difference: the online
version should omit certain information that the print manual must contain.

You might argue that the graphic in the print manual can contain the same
screenshot, complete with embedded help, but wouldn't our users holler if we
simply reproduced a screenshot with no explanatory text? In contrast, when
they're using the dialog box with the embedded help, the image is presented
in context (what they're actually doing), so they don't need that
explanation.

<<the best printed manuals were those that had the best linking,
cross-references, indexes, table of contents, and which could be read EITHER
cover to cover or picked up to quickly resolve an issue at hand. The
difference between such a manual and it's corresponding online help IMO is
only a difference in presentation.>>

Yet the presentation isn't merely a matter of what you've called a template.
Consider, for example, the problem with linking: if you choose to "open link
in new window", this quickly lets you fill a monitor with dozens of windows
of related topics, which you then need to organize in some useful way.
Conversely, you can follow a traditional trail of hyperlinks in WinHelp
until you're so far from your starting point that you forget where you
started and why you followed this trail. Getting "lost in hyperspace" is
much more common than getting lost in a book because the book provides
physical referrents to tell you where you are.

<<Looking at the two as entirely different entities is what I would believe
to be the reason we have haphazard online help with little indepth
information continuously referring back to printed documents and documents
from which it is difficult to figure how to simply use the software to
perform a task.>>

Poor online help arises from two main factors: a lack of understanding of
user needs (or lack of skill in meeting these needs), and a lack of time to
produce a helpful help system. Nothing whatsoever to do with the creator's
difference in perceptions of the media, since the exact same criticism can
be leveled (with considerable justice) at many printed manuals.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The skill of writing is to create a context in which other people can
think."--Edwin Schlossberg, designer (1945- )

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.