Re: Single Sourcing (kinda long, sorry)

["Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>]

David Castro wrote:
>>I think that, in theory, single-sourcing is wonderful, but in execution, its
>>inherent problems are pretty obvious.

Which prompted Lee Bumgarner to post:

>Since my task is to research it in general, review the products, and make a
>recommendation, I'd like to hear your pros and cons and an enumeration of
>its inherent problems.


First, recognize the difference between online documentation and online
help. When you set users expectations for online documentation, they
expect a digital book. The contents topic functions the way a table of
contents functions in a book, the index functions similarly as well,
and the information is organized in chapters, sections, etc. It is
relatively easy to write a book that functions well on paper and
online. In general, you make sure that information is "chunked" well;
cut back a little on the "transitional" text that you'd normally put
in a paper book; maybe you pull procedures and illustrations out of
the main text flow and present them in secondary windows.

The purpose of a book is to present information on a given subject,
usually in a cohesive and linear style -- at least for any given
subject and even if each subject is treated as a distinct and
separate entity. In other words, it may be a book of short stories
or one long story, but each story is a complete and linear narrative.

Online *help* is a totally different beastie. Users expect online
help to be presented differently, chunked differently, and written
differently. The purpose of online help is not to tell a story, but
to present the answer to a single question; to provide "information
on demand" in separate and discrete bites. Good online help provides
just enough information to answer users questions and get them back
to work quickly.

When you write for online help, each topic must be able to stand alone.
There is no narrative in which the topic takes its place. We can link
topics together to establish relationships between them, but there is
no guarantee that users will access all topics within a link set, nor
is there any guarantee that users will enter the linked set of topics
at the beginning and read to the end -- there is no beginning and there
is no end, there are only discrete bits of information.

Usability tests indicate that users access online help for between
30 seconds and 2 minutes at a time. This is precious little time in
which to convey information. Traditional "bookish" text with its
linear, building-block approach to information does not work well
in fulfilling users expectations for online-help-type information.
There is too much of it, and it does not organize the information
to facilitate an "answer my question" access style. It tells a story.
Online help users don't want to hear a story. They want their question
answered.

Attempting to single-source online help and a user manual must, then,
short-change one presentation medium or the other. If the text is
written for paper, the online help becomes cumbersome and not as
helpful as it might be if the information were designed for the
help system. If the text is written for the help system, the book
becomes disconcertingly non-linear and may appear to the user to
be snippets of information thrown helter-skelter on the page (because
it is).

In addition to meeting users expectations about online help, a good
help system facilitates information access by placing specific types
of information where the user expects the information to be. Context-
sensitive information is attached to the dialog box, either as a help
topic that just contains field information or as pop-up "What's this?"-
style help. Procedural information is keyworded or indexed well because
most users search for procedural information rather than browse to it.
If you're adapting a book to an online help file, it's difficult to
put each discrete bit of information where it belongs.

Conceptual information, OTOH, can be minimized online. Most users make
the distinction between "looking up something" in the online help file
and "reading about something" in a book -- and most users still prefer
to obtain their conceptual information from paper pages, not electronic
ones.

This is not to say that online help and user manuals cannot share
a fair amount of information -- they can share that information and
present it successfully if you plan well. There is, however, some
information -- particularly the long-and-involved conceptual stuff --
that will be accessed online so seldomly that it's just about useless
to put it there. Likewise, there is some information -- field-specific
stuff, for example -- that you can eliminate in the paper docs without
feeling guilty.

Sorry I've gone on for so long. I hope I've answered some of your questions --
although I've probably raised more questions than I've answered. Maybe that's
not a bad thing. ;-)



Sue Gallagher
sgallagher -at- expersoft -dot- com
     -- The _Guide_ is definitive.
        Reality is frequently inaccurate.