Re: Calling all Technical Editors again!; Was, "RE: Writing Corrective Actions for customers?"

Subject: Re: Calling all Technical Editors again!; Was, "RE: Writing Corrective Actions for customers?"
From: Ned Bedinger <doc -at- edwordsmith -dot- com>
To: Michael West <mbwest -at- bigpond -dot- com>
Date: Thu, 24 Apr 2008 17:44:28 -0700

Michael West wrote:
> Ned wrote:
>> I've come to the conclusion that understanding the material on an
> intellectual
>> level is paramount, and I know what happens when writers don't. It can
>> be a big black eye on technical writing. I think our reputation is
>> pretty well shot because of it.
> "Understanding the material" is _part_ of the technical communication
> process, not a prerequisite to it.

Where does it come in the "process"? First sounds right to me, but
maybe it is the age-old question of egg or chicken first.

> But even more "paramount" than that is
> understanding the specific information need of the audience, and how it can
> best be met.

The information has implicit structure and syntax. Where would you
begin to understand the audience's needs if you didn't understand the
information they're needing?

Because nobody's paying you just to learn things that your
> audience doesn't need to know.

I'd be surprised to learn they're paying you or me to take the time to
learn the concepts behind a product, needed or not.

For example, if the subject is network infrastructure development and my
SME is the network architect, how many questioning looks should I expect
to be allowed while he's checking me out with talk about octets and
masks, vitualization, packets and protocols?

My tech writer doll, who has the ideal characteristics of a tech writer,
speaks the language of SMEs and users, has the concepts, and doesn't
have to muddle around. One tech writer doll gets that knowledge from
school, another gets it from experience on the job, but they don't
become communicative with the SMEs or users by virtue of first having
writing skills or empathy.

I'd like to have a tech writer does who does, though.

> When I pick up a manual to look up how to do what I need to do, I care not
> one whit how much the author of that manual knows. It is a matter of supreme
> indifference to me.

This is a matter of process. The tech writer in the network engineering
example above is a good enough case of why, IMHO, the role of this
author you're describing couldn't accomplish the work you're attributing.

Suppose a User says, "Writer, I need cross-reference tables so I can
find and source Korean replacement roller bearings when the OEM
German-made bearings wear out."

If the author had those tables already available, fine, no need to know
any more about it. The work could be done by the mailroom clerk or the
holder of the patents form roller bearings, and it wouldn't matter.

But if the author had to start from scratch learming what roller
bearings are, what types are made in Germany, what Korean ane German
manufacturers to contact for specifications, and how to compare Korean
and German rating systems, and whre to look for thi9s sort of
information, then the turnaround time on the user's request would leap
from a day to an impractically long time. Wouldn't it?

That is the assumption I'm making about why the writer needs the knowledge.

> ALL I care about is whether the one bit of information I need RIGHT NOW is
> in there, and easy to find, and, once found, easy to follow. The last thing
> I want is a manual written by a technical expert who wants me to know how
> clever he is.

Define clever.

> To whatever extent "our reputation is shot" (as Ned puts it), it isn't
> because we aren't subject matter experts.

So when I pick up a manual expecting to find information that
comprehends what I need to know, and instead I find it has little blurbs
of uninformative filler designed to make the manual look about the right
size, it isn't because the writer isn't a subject matter expert. It is
because ...

> It's because we haven't learned
> how, after gathering the right information from subject matter experts, to
> put it into a structure that our users find easy to access and easy to
> understand. We haven't learned to speak the users' language and address
> their specific information needs.

Sorry, this may be your experience but it is not mine.

For example, when I boot my PC and hit <Del> to set up BIOS parameter
values, I need to know what those parameters are about. I look in the
online BIOS help, but it is pathically uninformative. I look in the
motherboard documentation, and it says exactly what the online help
says. I trace the BIOS back to the manufacturer, who looks it up, points
me to a web site where I can read the specification. I need a monster
amount of knowledge to get what I need from the spec. It is very technical.

I don't think my problem, as user without much expertise, is supposed to
be "learn all about BIOSes, although that is how I could approach it,
given time. If the tech writers were rendered ineffective because they
find a way to get the information to me, or to put the information in a
form I could use, I think they'd at least have a way to provide what
they COULD do, as a low- or no-cost electronic file on the manufacturer
web site. Anything they can do to translate the manufacturer's spec
into user documentation would be an improveent.

> Recently I was introduced to my firm's managing director by the CFO, who
> said, "This is the guy I was telling you about. He's a translator from techo
> to Human."

I'd just like to point out that this also makes my point, unless you can
translate to Human without understanding the Tech.

> THAT is where we can make a difference.


> The engineering schools are full of experts.


> What the business world wants is someone who can bridge the
> information gap between those experts and people who have other fish to fry.



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: Calling all Technical Editors again!; Was, "RE: Writing Corrective Actions for customers?": From: Michael West

Previous by Author: Re: Calling all Technical Editors again!; Was, "RE: Writing Corrective Actions for customers?"
Next by Author: Re: Apologies
Previous by Thread: Re: Calling all Technical Editors again!; Was, "RE: Writing Corrective Actions for customers?"
Next by Thread: RE: Calling all Technical Editors again!; Was, "RE: Writing Corrective Actions for customers?"

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

Sponsored Ads