Re: "Two-track" documentation?

Subject: Re: "Two-track" documentation?
From: Catharine Strauss <cstrauss -at- epicor -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 13 Dec 1999 16:50:56 -0600

Tom Murrel said:
"Yes, you want to write technically accurate information in a clear and
concise manner, but if you aren't writing
it TO someone, you are, at best, wasting your time, because no one will be
reading it.

In response to Plato's comment that:
>I've written numerous books to dual and triple audiences (and some of them
didn't suck!). I think all good technical manuals should write to various
levels of readers. The single audience concept is <insult snipped>

Tom also said:
"If you try to write for everybody, nobody gets anything out of it."

????????????????

My question is: What constitutes an audience?

Do people of three distinct skill levels constitute one audience, or three?
What if the skill levels are more varied, and could be subdivided into 7
different categories, from my grandmother (who just bought her first
computer), to my mother (who works in web page design), to a friend who is,
in fact, a rocket scientist?

In SOME cases, (note the lack of a general rule for every tech writer on the
planet) the intended audience is made up of people with vastly different
skill levels. Unless you are writing for the members of a class which had a
closely monitored sequence of prerequesites, how can you determine exactly
the skill level of your audience? And how can you justify the cost of
creating a different set of instructions for each? How do you account for
the self-taught system administrator who doesn't have the expected jargon
level determined by her title, and thus misunderstands the instructions, or
the newbie in a company that just went through a slew of layoffs, who needs
to perform a process not documented because it was considered "over his
head?"

And above all, what use are the instructions to anyone, if between step 9
and 10 (step 4 and 5 of the beginner's manual), you forget to tell the user
that they should reboot before continuing?

Bad information, no biscuit.

Isn't the information what it's all about? Yes, making sure the audience
can understand is a priority, but it comes after making sure that you, as
the writer, have the facts straight. Then you can worry about the users who
need more, or less, explanation.

That is what I got out of A. Plato's call for llama herders. You're not
going to make ANY audience happy if the information you give them is flawed,
no matter how well the instructions cater to their education and skill
level. On the flipside, information is also flawed if it is misunderstood
by the audience. We're trying to answer their questions, not our own. But
we can't make a separate manual for each user, and making several different
manuals (even with broad classifications of newbie, experienced, and expert)
can be dangerous because you always risk leaving something (or someone) out.


If a user doesn't feel that you are writing to them, you do risk that they
will lose interest. But assumedly, if the information is what they need,
they can put up with it. If 1% of your users skim the manual instead of
reading it intently, you haven't failed. As long as you put what they need
where they can find it; the information is there, the user finds and uses
it, nothing smashes into a small red planet, the user goes home happy and
their company pays your company so that they can keep you gainfully
employed.

Audience IS important, but I agree with the assertion that we are technical
writers, not audience writers. That's a whole 'nother group (See UTEST -
utest -at- hubcap -dot- clemson -dot- edu, which I heartily recommend).


-Catharine Strauss
Knowledge Engineer
Epicor Software Corporation

P.S. I have no comments to make about how Andrew Plato is smearing the noble
name of Puritans everywhere with his comments about technical writers and
drowning witches. I will allow for a brief chuckle for those who leapt on
that as proof of his inability to write for a politically correct audience.





Previous by Author: RE: Guide to writing online help for web app
Next by Author: RE: MS Project alternatives?
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