Re: On-Line Vs. Print, Single-Sourcing, and how to ignore the obvious

["Doc" <doc -at- vertext -dot- org>]

Hi Andrew, welcome back!

I hope you'll stick around for a while. As Kaspar Gutman (Sidney
Greenstreet) said to Sam Spade in the Maltese Falcon, "I distrust a
close-mouthed man. He generally picks the wrong time to talk and says the
wrong things. Talking's something you can't do judiciously, unless you keep
in practice. Now, sir, we'll talk if you like. I'll tell you right out, I'm
a man who likes talking to a man who likes to talk."

"Andrew Plato" <gilliankitty -at- yahoo -dot- com> wrote in message
news:163859 -at- techwr-l -dot-  -dot-  -dot- 
> You kids can yammer 97 ways to Sunday about the
> theoretical value and difference and similiarites
> between on-line and print - but the cold, hard, stiff,
> face up to it fact is - they are different and they
> are read differently.

I've been watching users work with documentation for 20+ years and my
perception is different.

Users have told me that they like paper manuals. They claim to read them
while commuting. Some claim to read the entire manual from cover-to-cover
before installing the software. But when you observe their use of the
software and documentation a very different picture appears.

Bear in mind that the following is a generality and there are, of course,
deviations.

The user takes a quick glance at the installation instructions, leaves the
book open, and installs the software.
If there are problems or special requirements for installation the user
refers to the book briefly.
Once the installation is successful the user may, but more often may not,
work through a printed tutorial or "Getting Started" section.
The book is then closed and the user proceeds to try a first task.
If it is successful, they proceed to a second task.
With each success the manual drifts further and further away, eventually
being placed on a shelf.
When a failure occurs, the user opens the help file.
If the help file doesn't, the user opens the manual to the TOC or, more
often, the index to look for the answer to the specific problem.

This seems to be true of about 90%+ of users who have a background in the
subject matter. By that I mean, users who understand the task that needs to
be performed and for whom only the software is new.

*Ad hominem snipped*
> ... the way I consume data from a
> hyper-linked web site or on-line help is fundamentally
> different then how I consume data from a piece of
> paper.

Of course not, but that doesn't mean the data is different, merely that the
way it is displayed and navigated is different.

> Hence, this is one of many millions of blatantly
> obvious concepts that the single-sourcing lunatics
> just want you to mildly forget about.

As a card-carrying single-source lunatic I certainly don't want you to
forget about it. As I have said in previous posts, single-source is about
content NOT delivery. If you write good content then the method of delivery
should be secondary. Too often the print medium is used as an excuse for

*Snip*
> I invariably wind up researching the matter on my own
> and then trying to integrate that knowledge with the
> asinine ways that is implemented in whatever product I
> am using.

There is some dependency on the type of software being documented, and the
user's experience with the concepts behind the software.

If the documentation is expected to provide a conceptual framework for the
software, there can be an expectation of a narrative linearity. A program
designed to introduce beginners to the subject matter could and should
assume that there should be a significant amount of explanation of
terminology and methods.

OTOH you need to be aware of diminishing returns. A word processing program
aimed at the educational market may have a substantial amount of information
about grammar and usage, but one aimed at the general market will assume a
basic knowledge. Obviously, there must be some basic explanation of concepts
and terminology, especially if the software uses them in any quirky way.

I contend that what you complain about is exactly the way it should work. My
job as a technical writer is not to teach you how to construct a sentence or
how to invest, how to manage a network, or how to design a good-looking web
site. My job is to teach you how to use the software, usually a
non-theoretical activity. If the company chooses to espouse a particular
method then explaining it becomes part of my job. But unless that's the
case, it is not up to me to educate you on theory.

As I said before Andrew, good to have you back. Whether I agree or disagree
with you, you help crystallize ideas.

To paraphrase Samuel Johnson, "Depend upon it, sir, when a man knows he is
arguing with Andrew Plato, it concentrates his mind wonderfully."

-Doc
---------------------------------------------------------------------------
David 'Doc' Lettvin
VerText
"Versatile Text for reusability and globalization"
http://www.vertext.org
vox: +1.978.468.1105
fax: +1.775.248.0508





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L. 
http://www.cafepress.com/cp/store/store.aspx?storeid=techwhirl

Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!
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.