Re: Archimedes Socrates, ace tech writer, wins another one

Subject: Re: Archimedes Socrates, ace tech writer, wins another one
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 2 Sep 2001 03:02:37 -0700 (PDT)

"Michael West" wrote...

> Are communications skills not worth a mention here?

It was mentioned. It is one side of the picture. Lacking either side is
a lacking as whole. You cannot be a skilled technical writer and not
possess technical skills. Its in your job title: TECHNICAL writer.

> Or is "documenting complex technology" something
> grander and more exalted than telling some poor sod
> clearly and simply how to install a firewall router ?

No, they are one in the same. A firewall router is a complex piece of
hardware or software. If you don't understand how it works, what its
purpose is, or why it does certain things - you won't be able to tell that
poor sod how to use it. Or more importantly, you won't understand the
instructions given to you, and as such you won't be able to make
judgements about the text and what is important and what isn't.

> What I would like to know more about is what
> happens after "anticipating" that makes you know
> "how best to explain" something. For me, the
> anticipation is only the beginning. Knowing *what*
> needs explaining does not make me know *how*
> best to explain it. Is it different for you? Do the
> mechanics of clear communication just follow magically
> upon your anticipation?

I think an example is in order....

Recently a writer at my firm was assigned to produce a migration guide for
the new version of a product. He's a good writer with good communication
skills. He was working with an engineer who is very helpful. The document
this writer produced was clearly written and described every step in good
detail. Technically, the instructions and content were correct.

The problem was - if you followed those instructions you would have been
mired into an extremely frustrating situation. There were too many "error
prone" instructions. Many instructions were mangled in the process of
wordsmithing. Some extremely important aspects of the procedures were
"blurred over" while phenomenally mundane things were given great

Because I knew SQL Server and the product involved, I knew the
instructions would frustrate users. So, at my insistence and direction,
we rewrote and reorganized the guide. In the process, or analyzing the
information, we discovered there were easier ways to get the job done.

The end document was far more usable and helpful. When we returned the
document to the client, the lead engineer said "this is a thousand times

Were I ignorant of the product or SQL Server, I would have signed off on
the doc without a care in the world. And my client would have had many
unhappy customers.

> Without wanting to get into a chicken/egg circularity,
> *I* have found that the more closely I adhere to rules
> of clear communication, the more I am required to
> discover about both the subject matter and the user's
> requirements. (This is because clear communication
> requires clear thinking.) So for me, the dictates of clear
> communication compel me to increase my knowledge.
> For you (apparently) something like the reverse is true.

I just don't emphasis "clear communication" as much. To me, clear
communication is so basic, its not even worthy of emphasis. Its like being
able to type - of course I have to communicate clearly. That's not the
problem. The problem is - what the hell am I communicating? I am
waaaaaaay more concerned with what I am writing than the exact method of
how it gets across.

Fixing mangled English is easy, fixing inaccurate information is much

The way I see it, I have matured to a level in this profession where I can
look beyond tools and the rules of English and focus on the information I
am communicating. It is after all, the most important aspect of my work.

Andrew Plato

Do You Yahoo!?
Get email alerts & NEW webcam video instant messaging with Yahoo! Messenger


A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: +++

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: Archimedes Socrates, ace tech writer, wins another one
Next by Author: Diverse Tools (was HTML editors)
Previous by Thread: Re: Archimedes Socrates, ace tech writer, wins another one
Next by Thread: Re: Archimedes Socrates, ace tech writer, wins another one

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

Sponsored Ads