Re: Engineers as Writers

Subject: Re: Engineers as Writers
From: Pam Tatge <pamt -at- STEINBECK -dot- SC -dot- TI -dot- COM>
Date: Wed, 18 Aug 1993 10:43:41 CDT

Bradford Morgan writes:

> I'm still trying to collect additional insights into
> what are the current writing practices of engineers--and find
> the point at which the engineer or scientist yields to the
> professional technical writer.

"YIELD" to the writer?? You mean, at which point do they hand
us a complete, well-written document that we can mangle as we
please, with no further input from the subject-matter expert
(or marketing, or the software developers, or the hotline
staff....)? :)

We work under two scenarios in our documentation group. In
both cases, the concept of yielding as far as "handing it
over" doesn't apply. The first scenario (here it comes, sorry)
applies to REAL technical writers and the second applies to--
uh--NOT real technical writers.

Scenario 1
The tech writers work with the engineers, marketeers, software
developers, etc., as a team. Sometimes, we receive very little
source--maybe just an unannotated list of commands. When we
know that we need more source from an SME, here's how we ask
for it. We ask them to remember the experience of writing a
report in college; usually, they would go to the library and
collect a bunch of information from a variety of sources.
They would base the report on this information, but the infor-
mation did not appear verbatim in the final report. We tell
them that the source material that they provide us will be
like the information they would have collected at the library--
it serves as the base of the document, but it isn't the final
document. We also ask them to write in a manner that explains
things to US (the writers). We tell them that they don't need
to write in complete paragraphs or even in complete sentences.
From that point, the writers work closely with the engineers,
getting clarification of source material and explanations to
help fill in the holes. And of course, the SMEs review what we
write to ensure that it is technically accurate. And, although
we welcome their inputs about how the document is written, we
make it clear that that is OUR field of technical expertise.

The SMEs that we work with in this manner are comfortable with
it, and most are relieved that they are not responsible for
producing A BOOK. Also, we find that when we work with SMEs
in this manner, they are more ready to listen to our inputs about
THEIR work (command names, interface issues, etc.)

Scenario 2
The SMEs write the documents. They pass it on to the writers,
who use our publishing tools to "make the book pretty". After
a review period, the engineer sits next to the writer and tells
him/her which comments to incorporate and how, which words to
make bold, which misspellings to correct, and how to make the
book look prettier. For whatever reason--intimidation, low
self-confidence, or (more usually) a deficit in skills--the
writer does not apply subject matter expertise or technical
communication expertise to the document. (Really, it's
amazing if we can get them to run the spellchecker.)

Of course, some projects fall between these two extremes. We
treat these as opportunities to show the SMEs how we can
make their lives easier. (We can't just tell them that we
write better than they do--that will only make them angry.)

The more people who can communicate well, the better. If you're
helping engineers and scientists to become effective communicators,
great. But to me, the word "yield" implies an "us-and-them"
situation, which is counterproductive. Good documentation is
a team effort.

Pam Tatge, Member Group Technical Staff
Texas Instruments Semiconductor Group, Houston
pamt -at- steinbeck -dot- sc -dot- ti -dot- com

Previous by Author: Re: Society for Documentation Professionals?
Next by Author: Re: Comment on terminology
Previous by Thread: Re: Engineers as Writers
Next by Thread: Re: Engineers as Writers

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

Sponsored Ads