Re: Outrageous: Was Pray for me

["Tim Altom" <taltom -at- simplywritten -dot- com>]

I have to disagree with your statement that so long as the printed doc is
accurate, an online version will be acceptable, too.

Pure content is extremely rare. Almost always, parts of the content rely for
their meaning on their proximity to other parts, which gives context. We're
often oblivious to this effect because we're so used to it. It's like the
wag who, when asked to quote two Bible verses, said "Judas went and hanged
himself" and "Go ye and do likewise". We blithely say "Oh, that's taken out
of context" but we don't often think what that means.

In this case, a 400-page manual is unlikely to be so "Lego-like" as to as to
be easily decomposed into fully independent pieces, as required in
hypertext. Look at almost any book you like, and imagine it broken down into
hundreds of hypertext topics. Even with "go-to" links between them, these
decomposed parts won't be able to stand firmly by themselves, and will often
be plagued with double meanings, misunderstandings, and the like. This
effect is made far worse in software manuals, because the same terms recur
in many places, things like "Print button" and "database". If the user
clicks a button or selects a menu item at the wrong moment, due to an error
in context, the results can be embarrassing or catastrophic. Further, no
user wants a help file that's essentially a series of slides, linked by "go
forward" and "go back" jumps. Yet, how can you produce a help file with a
single topic telling the user how to perform a task, when the information
may be scattered across pages or even chapters?

To be suitable for both hypertext and print (single source), a document MUST
be designed from the start to be workable in both worlds. The text and
graphics must be capable of decomposition and rearrangement, without losing
meaning due to context shift. That's why our Clustar System works so
well...it gives context that's consistent. The original 400-pager may have a
rough structure and may be technically accurate, but I'd bet that the
structure wouldn't stand up to a DTD, and that technical accuracy won't be
enough to ensure good single source material. Making the thing searchable is
just moving the responsibility for use to the user, which in my mind is an
abrogation of responsibility.


Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com

----- Original Message -----
From: Joy S. Kocar <jsk -at- isolns -dot- com>
To: Tim Altom <taltom -at- simplywritten -dot- com>; TECHWR-L
<techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Monday, July 24, 2000 11:43 AM
Subject: RE: Outrageous: Was Pray for me


> You make a valid point. Of course we don't want the documentation to cause
> harm to the operator or the patient. When I read the original post, I
> understood it to mean that they had a 400 page document that they wanted
to
> have available online. The document was written completely in Normal style
> with formatting changes done manually, not using heading styles, etc. This
> is not to say that the document has no structure. Nor does it mean that
the
> document is inaccurate.
>
> Slapping a document online is not necessarily a help system, just a
document
> in electronic form that is searchable. Not very useful but it is no more
> harmful than a printed document. I didn't interpret from the original post
> that the source document was erroneous, just formatted manually.
>
> Adding context sensitivity however, is a different story because then it
> becomes part of the software and should be tested and validated.