Re: "Two-tracked documentation"

Subject: Re: "Two-tracked documentation"
From: "Murrell, Thomas" <TMurrell -at- alldata -dot- net>
To: "'TECHWR-L'" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Tue, 14 Dec 1999 13:28:14 -0500

Susan W. Gallagher wrote:

Technical accuracy is certainly not the most important
characteristic of technical writing. It has to take a back seat to
relevance
and usability. Sometimes it doesn't even make it onto the bus.

I hope this doesn't sound inconsistent to anyone, but I would disagree with
this statement, too. Technical accuracy is VERY important in technical
writing. If the information isn't accurate, it is useless. If the
credibility of the information is even suspect, the information loses all
value. If the reader can't trust the accuracy, it doesn't matter how well
tailored to the reader it is; the information remains useless.

I don't see the audience as MORE important than the accuracy of the
information anymore than I see the information as more important than the
audience. Accurate information (and it MUST be accurate) must be crafted
with an audience in mind. What does this audience need? How will this
audience use this information? Where does the audience need to find this
information? When does the audience need the information?

These are all vital questions, but they cannot supersede the accuracy of the
information. Technical Writers, in my opinion, must do BOTH and do it well
and do it well ALL THE TIME. The information MUST BE ACCURATE and it MUST
BE FOCUSED on the needs of an audience.

Susan W. Gallagher wrote further:

Consider the typical documentation written by the engineer who is
untrained
in writing. Said engineer will go to great lengths to make sure that
the
doc is technically accurate. And certainly, a statement like, "this
sorting
routine uses the state-of-the-art, whizzbang sorting algorithm which
allows
you to sort megafiles in a fraction of the time" is technically
accurate.
But does it tell you how to perform the sort? Nope. So, technical
accuracy = 10 but relevance and usability = 0. So what good is it???
Ask the audience. It sucks.

I've even seen times when being technically accurate was a detriment
to
the docs because it made the view from the user's perspecitive
excessively
complicated. The user didn't need to know the details to get the job
done.
Those details just got in the way. For example, if the user needs to
sort
the information and the system actually copies the information
line-by-
line and then replaces the original text with the new, telling the
truth,
the whole truth, and nothing but the truth may only serve to
confound the
user -- depending on the audience.

I think you are confusing accuracy with appropriateness. The example you
cite seems to me to be a classic case of correct information (I will assume)
that may be of NO USE WHATSOEVER to the intended audience. What writers do
is include all of the relevant information, accurately, to the audience. We
get a lot of information from our SMEs that is important, we check it for
accuracy, then we determine what audience needs that information (See
questions above) and publish it to that audience. (Or not; information can
be accurate and irrelevant. In such cases, the writer discards it or files
it for later use.)

Finally, if I may be permitted a slight digression, Susan W. Gallagher asks,
"So, if the Prime Directive isn't technical accuracy, what is it?"

I thought everyone knew that the Prime Directive, also known as General
Order #1, forbade Federation Starships and Citizens from interfering with
the normal development of primitive planets (unless it was necessary for the
resolution of a story plot within the allotted hour). <g>

Seriously, I don't think Technical Writing can be reduced to a Prime
Directive. Information is not more important than Audience, nor is Audience
more important than Information.

Regards,
Tom Murrell




Previous by Author: RE: Interleaf to Frame
Next by Author: Re: Tracking Off
Previous by Thread: Re: MS Access and Word/HTML doc integration
Next by Thread: RE: "Two-tracked documentation"


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


Sponsored Ads