Re: Occupational hazard of techie tech writers

["Eric J. Ray" <ejray -at- RAYCOMM -dot- COM>]

At 04:13 PM 10/31/98 -0500, Carl Stieren wrote:
>If so, what do you think of this analysis:
>
>Anyone who is really into technology, and who becomes a technical writer,
>has advantages and one big occupational hazard:

<SNIP>

>Occupational hazard:
>
>* inability to explain software or functionality to a beginner (sometimes
>even the inability to realize that you NEED to explain the software to a
>beginner)

I don't buy it for a second. It's just as much a ridiculous generalization
as any I've heard this week. I'd actually go so far as to say that
your premise is fundamentally flawed. I respectfully suggest that
one of the fundamental characteristics of a good (or even adequate)
technical writer is a thorough understanding of audience and the
ability to address that audience. Without that understanding, you
have someone who writes, or someone who tinkers with technology,
but not a true technical writer.

<SNIP>
>Therefore, there's a problem. Any brilliant technical writer who's into
>technology and hasn't done a lot of technical writing is going to produce,
>as a first draft of a first project, a document that will fail usability
>testing.

First, I'd be pretty skeptical of a "brilliant" technical writer who
hasn't done a lot of technical writing. Does that mean that I'm
a brilliant programmer who hasn't done a lot of coding? Or a
brllliant chef who hasn't done a lot of cooking? I'd suggest that
you cannot be a brilliant technical writer if you don't have
the experience to prove it. You might be a decent tech
writer with enormous potential, but that's not what you're
asking. Brilliant technical writer...first draft...first project
(assuming you mean first ever) is oxymoronic.

Second, judging anything on the first draft of a first
project isn't exactly fair to anyone. Many technical
writers use a first draft of a first project at a new
company or in a new organization as a chance to get
solid feedback and additional information in term of
audience, goals, etc. I'm not saying that many tech
writers make stuff up or write ridiculous things just to
get reactions, but when assessing a project, it's rare to get
all of the information you need about the audience and
goals. A first draft for review that, for example,
explains some technologies thoroughly or glosses over other issues
is a good way to gain additional info about the goals and
focus of the document. "Hey... you wrote that fundamental
knowledge of SQL is assumed, but our sales people are
telling everyone that you need only use a mouse to
use our product successfully. I guess I forgot to give you
the sales literature and send you to the sales seminars."
"OK--I'll catch that in the next draft. "

Finally, back to your original point, (and I'm deliberately
trying NOT to open the techie vs. writer discussion, and
not specifying how people gain their knowledge), a person
who is really into technology--really into technology--can
be in a far better position to explain the technology than
one who isn't. For example, I was recently doing the technical
edit on a document that provided some basic information
about the Internet and Web to a non-technical and probably
inexperienced audience. The writer clearly knew just enough
about the topic to want to introduce topics like ports and
protocols...in the same section of the same chapter that
introduced the Web as "a collection of computers that hold
information for you to access" (which was an audience appropriate
generalization). Had this person really been into this
particular technology, or been a brilliant writer, or both,
it would have been clear that details like http standing
for hypertext transfer protocol or telnet using port 23
are completely out of bounds for the audience and purpose.

It's not an occupational hazard of techie tech writers--it's
an occupational hazard of poor tech writers.

Eric







^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Eric J. Ray    RayComm, Inc.
http://www.raycomm.com/      ejray -at- raycomm -dot- com

*Award-winning author of several popular computer books
*Syndicated columnist: Rays on Computing
*Technology Department Editor, _Technical Communication_


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=