RE: How do you define your audience/"user requirements" in your docs, to the reader?

Subject: RE: How do you define your audience/"user requirements" in your docs, to the reader?
From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
To: "Michael West" <mbwest -at- bigpond -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 9 Apr 2008 09:02:28 -0700

> Mike West stated: I don't know how you could have written a usable
manual without a clear idea of what roles you were writing for.

Although several Techwr-lers have provided very helpful feedback, Mike
is at least the second person to post without understanding what I was
asking. Since this thread is still going, I'd like to clarify.

I know my audience, and I know what they are trying to do. The problem I
was struggling with was how to represent the target audience, concisely,
to the target audience itself. In other words, how can I best describe
the user so that the user self identifies correctly? This is more
difficult than it sounds because of the dual dependencies of
metacognitive competence and marketing. On one hand, "People tend to
hold overly favorable views of their abilities in many social and
intellectual domains ... this overestimation occurs, in part, because
people who are unskilled in these domains suffer a dual burden: Not only
do these people reach erroneous conclusions and make unfortunate
choices, but their incompetence robs them of the meta cognitive ability
to realize it" (http://c2.com/cgi/wiki?UnskilledAndUnawareOfIt). On the
other hand, if you define requirements so rigorously that even someone
with little or no metacognitive competence will recognize, "gee, I
probably won't get this," you also will probably scare off precisely
those to whom most technical documentation is geared--since people whose
"competence falls in the scale of 60 to 70 percent ... are the ones that
trust their abilities least" (ibid.).

Task based descriptions of audience don't address these challenges
because they say nothing to those who do not already have metacognitive
competence in the task domain. Let's look at example suggested by Mike:
"This manual is for people who want to create an ILM system using System
X." It's accurate but no more useful than, "This guide is intended for
users of System X." Why? Someone may sincerely want to create an ILM
system, but if he doesn't understand enough about PCs to know that a DVD
tray is not a cup holder, it ain't gonna happen.

Mike's second attempt isn't any better: "If you already have a basic
understanding of <subject matter>, then this manual is for you. If not,
you should probably read <some other document> before attempting to use
the software." First, "basic understanding" doesn't resolve the problem
of metacognitive competence. Second, this formulation is problematic
from a marketing perspective. The more hurdles you put in user's way,
the less likely he is to use your product.

Because of these considerations, I am strongly leaning toward John
Posada's suggestion: "You don't have to define your target reader to
your user. If they picked up the manual and are getting use from it,
they ARE the target. What you need to do is to not miss ones you should,
and not waste time writing for someone who couldn't care." It follows
from the considerations I talk about above, and it speaks to how most
users use tech docs.

For now, I simply speak of what the manual covers and does not cover:
"This user's guide is intended for users and system administrators. It
documents <PRODUCT> functionality and avoids documenting OS procedures."
I then go into detail about what "<PRODUCT> functionality" comprises.

Leonard C. Porrello


-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of Michael West
Sent: Wednesday, April 09, 2008 4:01 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: How do you define your audience/"user requirements" in your
docs,to the reader?

"I was wondering how to deal with the challenge of defining my target
audience explicitly--in my docs, to the reader. I have hardware and
software
requirements, but I do not have "user requirements," nor do I have a
clear
idea of how to define my target user--to the reader. I have the
standard,
"This user's guide is intended for users and system administrators," and
while "system administrators" is useful, "users" isn't saying much."
-------------------------

No, it isn't; and I don't know how you could have written a usable
manual
without a clear idea of what roles you were writing for. And by "roles"
I
don't mean job titles. I mean what they do -- what tasks they perform.

My suggestion is to define your audience in terms of what it is that the
manual you've written is supposed to help them do. Specific tasks, I
mean.

"This manual is for people who need to do x, y and z using the
Superdupersystem."

Depending on the complexity and scope, you might want to delineate some
further boundaries:

"If you already have a basic understanding of <subject matter>, then
this
manual is for you. If not, you should probably read <some other
document>
before attempting to use the software."

Focus on the What rather than the Who --- that way, it should become
immediately clear to the poor sod holding your manual whether it
contains
anything he or she needs.

To find out more about your audience, you may need to speak to sales
staff,
tech support staff, marketing staff -- or (drastic as it may sound!) the
poor users themselves.

Often the system developers know very little about the users. Sad but
true.
On the other hand, that's why WE have jobs: to fill that knowledge gap.
--
Mike West
Melbourne, Australia






^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats
or
printed documentation. Features include support for Windows Vista & 2007

Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as
Leonard -dot- Porrello -at- soleratec -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit
http://lists.techwr-l.com/mailman/options/techwr-l/leonard.porrello%40so
leratec.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.


References:
Re: How do you define your audience/"user requirements" in your docs, to the reader?: From: Michael West

Previous by Author: RE: Please describe value of Information Mapping
Next by Author: RE: How do you define your audience/"user requirements" in your docs, to the reader?
Previous by Thread: Re: How do you define your audience/"user requirements" in your docs, to the reader?
Next by Thread: RE: How do you define your audience/"user requirements" in your docs, to the reader?


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


Sponsored Ads