Single sourcing and embedded assistance?

Subject: Single sourcing and embedded assistance?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 17 Sep 2002 12:56:22 -0400

Joanne Vinton wonders: <<Studies have shown that users don't read paper
manuals or online help, so writers are now trying embedded assistance along
with context sensitive help. I'm looking for opinions:>>

The phrase "studies have shown" always sets off alarms in my head. Which
studies, which users, and which conditions? I think it's truer to say that
people only read manuals and use help in certain situations, and if we can
understand those situations, we can learn what information belongs online
and what belongs in print--and what belongs in the interface itself, which
brings us around to your actual question:

<<Could embedded assistance completely replace paper manuals and online

In theory, yes. The Holy Grail of interface design is to produce an
interface so easy to use that documentation outside the interface itself is
unnecessary. By no means does this imply that the interface must be
intuitive to use; rather, it means that the interface itself should provide
sufficient knowledge that the user doesn't need to look elsewhere to find
out how to do something. A completely intuitive interface is probably
impossible to design; one that is entirely self-supporting isn't.

I see our profession heading very strongly in this latter direction. We
don't all have the luxury, as I do, of working with programmers to reshape
the user interface itself. But just about all of us have the ability to talk
developers into changing the interface labels and adding minor clues
(affordances) that make the existing interface easier to understand.
Building these relationships lets us start small ("you spelled that
wrong!"), grow slowly ("erase is a better word than disintegrate for that
function"), and eventually start guiding the interface itself ("these fields
could be grouped under a single heading, and should be dropdown picklists,
not radio buttons).

<<If so, would single sourcing have any value?>>

In the long term, no, but mostly because of the definition we're working
with: single-sourcing is useful when you need to deliver subsets of a larger
body of information in different combinations in different media. The goal
is to reuse information so you don't have to write it twice, but if the
information is presented in the right place to begin with, there probably
shouldn't be any overlap between the online and in-print information, and
that virtually eliminates the need for single-sourcing. If all the
documentation becomes embedded in the interface, then there's only one
medium to worry about: online information. Any information that doesn't
support use of the product could remain on paper or become part of support

For example, a traditional installation guide doesn't belong online because
you'd only be using the guide while the software is still halfway between
the CD and the computer; once it's installed, why would you need an online
installation guide? A more modern installation guide takes the form of an
installation wizard that combines the instructions with the act of following
the instructions, so you'd never need the printed manual; all the
instructions are right there in front of you, when you need them. If you
ever had to reinstall or customize the software, details on how to do that
would be part of the interface of the installer/customizer itself.

Modern installers are either too inflexible to support radically different
installation approaches, or are not used to their full extent; thus, they
have a highly linear approach and don't let you diverge from that approach
to suit different needs. For example, I haven't yet seen an installer that
shows you how to define your needs, then uses that definition to create an
installation script that is unique to meeting your needs. By "definition", I
mean the sort of process in which the installer tells you what you need to
plan a complex installation, lets you enter the planning information, and
then sets up an installation script that follows your plans.

Here's my pie in the sky ideal: The information is integrated so well with
the process that you always see the necessary information for the current
stage in the process. Because the information is all present, you never need
to look elsewhere for it, and thus, documentation per se vanishes: it
becomes part of the process. Now getting there... that's the challenge.

--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
Hofstadter's Law--“The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's

Absolutely FREE! FrameMaker/Win 6 & 7 Express Customization (v3):
Quick-access buttons & keys to common functions, char tag/font drop-down
lists, charset browser, QRef guides & much more:

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever!

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 for more resources and info.

Previous by Author: Tables "tied" to section breaks?
Next by Author: Tutorial without final data (%, $)?
Previous by Thread: Domentation Structure and Content Model
Next by Thread: Multiple help files in RoboHelp 2002

What this post helpful? Share it with friends and colleagues:

Sponsored Ads