Re: "Two-track" documentation

Subject: Re: "Two-track" documentation
From: "Mark Baker" <mbaker -at- omnimark -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 13 Dec 1999 11:36:21 -0500

Brady, Joy wrote

> For the life of me, I cannot understand how audience consideration
> and technical accuracy are mutually exclusive.

Of course, the contrary is the truth. Technical accuracy and audience
consideration are mutually dependant.

Manifestly, you do not serve any audience by misleading them.

All statements are designed to communicate and must be made in a language
common to the speaker and the listener. There are no statements that are
accurate in abstract. Statements are accurate in communicating to a given
audience. (A shot cannot be accurate in abstract, it can only be accurate in
hitting a stated target.)

There is, of course, a tendency to treat the most common audience for
statements on a given topic as the norm for such statements. We betray this
when we state something one way and then, in parentheses, say "technically"
and state it another way. "Technically", in this sense means "in the
language of the cognoscenti of this discipline".

But being "technically accurate" should not mean stating things in the
language of the cognoscenti. It should mean causing the intended audience to
act correctly. Stating things in the language of the cognoscenti does not
always have this effect. A statement may be accurate for one audience and
not accurate for another audience, in that it causes the first to act
correctly and the second to act incorrectly.

It should be noted that using the language of the cognoscenti does have the
sometimes desirable effect of persuading the user that they need to educate
themselves before performing a particular task. But in our current world of
rapid devolution of technology, this seems to be the exception rather than
the norm. Indeed, the growth of the technical communication profession may
be largely attributable to this devolution.

BTW, I think Andrew Plato is very reasonable in stating a preference for
writing for a certain kind of audience. It is entirely appropriate that an
author specialize in an audience they enjoy writing for. In many cases, it
is harder to learn an audience than to learn a technology.

Incidentally, I find one of the most persistent misconceptions among people
near to a product is the idea that every user intends to become a
cognoscenti. I constantly have to fight against the notion that new users
want be, and eventually will progress to become, enormously knowledgeable
experts, and that the purpose of the documentation is to make them such
experts. The truth, for most users of most products, is that they want to
know just enough to get their jobs done.

Mark Baker
Senior Technical Communicator
OmniMark Technologies Corporation
1400 Blair Place
Ottawa, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com

Previous by Author: Re: Future XMLers (was document management and xml)
Next by Author: Re: object-oriented documentation
Previous by Thread: RE: "Two-track" documentation
Next by Thread: RE: "Two-track" documentation

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

Sponsored Ads