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

[Ned Bedinger <doc -at- edwordsmith -dot- com>]

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. 

yes

> The engineering schools are full of experts. 

Yes.

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

YES!


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

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.