RE: know your ... who?

Subject: RE: know your ... who?
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: "Lauren" <lauren -at- writeco -dot- net>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 20 Feb 2008 13:07:56 -0500

Lauren replied:

> > "Be one of the people to whom your documentation is addressed"
> >
> > OR
> >
> > "Make educated guesses, based on assumptions about the people to
> > your documentation is addressed."
> >
> > Is that a good summary?
> No. It isn't.
> "Knowing" one's audience does not mean "be one of the people" or make
> "guesses" about the audience. In my high school graduate audience
> we've graduated high school so we should "know" how a high school
> learns, since we have been in that position ourselves. If we wrote
> the
> perspective of "being" a high school graduate, then we would write
> If
> we made "guesses" about high school graduates, then we would not do
> jobs
> as writers. If we have not been in the position of the audience, then
> should learn about the audience so that we can know the audience.
> and
> other staff are good resources to interview to understand the audience
> the document.

Subject Matter Experts are great in their areas of Subject Matter
Expertise, and sometimes for other purposes, too. However, what's the
I get next to developers when it's a question of the SDK portion of my
customer docs. Along with the dry syntax lists of functions, options,
calls and errors, I like to include tips, tricks and hints when I can
glean them. I correspond with the Sales Engineers and Customer Support
bodies when it comes to configuration and administration issues, as well
as some SDK-related stuff. I'm especially fond of the Sales Eng guys who
provide examples of (as somebody else mentioned in the thread) uses that
we never intended for the product.
We also have crypto and security specialist who has been known to have
the occasional useful comment (he's a brilliant man, and a capable
communicator, but it's rare that I need material at his level), and we
have people whose job it is to deal with standards agencies (NIST/FIPS,
Common Criteria/EAL, etc.). But none of these people are my end-users,
and none of them are doing what the customers are doing. I do get good
stuff from the field people, but what are they leaving out? What do they
forget? What did they never see?
Obviously, your high-school grad example was not apropos for me, but
even as an illustrative example it's missing a big dimension. I was once
a high-school grad, but my high-school experience was in one of the
poorer regions of one of the poorer provinces of Canada (35 years ago).
I would have some areas of commonality with (say) USians, but I daresay
plenty of differences. Now, how about the high-school graduates in my
audience from Bangalore, Singapore, or Burley-Heads Australia, from
Seoul, from Buenos Aires, Santiago, Fez... ?
As I said, my audience is global and comprises mostly engineers and
technicians, but with a wide range of pre-existing experience (or
non-experience) in the cryptographic and security milieus. Because our
products are very flexible, the customers also have a wide variety of
uses to which they put those products. Some are mutually exclusive - you
have to turn off certain functions of the appliance before others are
allowed... and so on.
So, a lot of audience variability, and they're all far, far away. What I
produce for them comes down to a best-guess, based on all kinds of
things. Not, as some have implied, based on nothing.
Yet, there indeed ARE industries and companies where long development
cycles are the norm, and there literally is the opportunity to poll
groups of representative customers or sit representative people down
with the product (prototype?) and documentation and observe them as they
figure out what to do... or fail to. THAT is what I call knowing your
customer. That is also what some other people call knowing the customer
when they imply that that's what I should be doing, despite the
different circumstances (not saying that you ever said that). What I do
is not "knowing my customer". It's more of an educated "imagining my
customer". I think that's as close as many of us can realistically get.
Oh the ignominy of it all.

The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.


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.

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

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

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 for more resources and info.


RE: know your ... who?: From: McLauchlan, Kevin
RE: know your ... who?: From: Lauren

Previous by Author: RE: know your ... who?
Next by Author: RE: know your ... who?
Previous by Thread: RE: know your ... who?
Next by Thread: RE: know your ... who?

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

Sponsored Ads