Re: Professional respect

[SteveFJong -at- aol -dot- com]

Meena S <meena -at- thinkbn -dot- com> tells us she don't get no respect. Believe me, 
Meena, we've all heard that before!

I fully agree with the advice of Bill Swallow (first of several) that respect 
is earned. Toward that end, in thinking about this issue in the past, I wrote 
up a list of ten specific ways in which technical communicators add value. 
The more of these things we do, the more respect we earn. I think the list as 
apropos, and I offer it for your consideration.

        -- Steve

TEN WAYS TECHNICAL COMMUNICATORS ADD VALUE TO DOCUMENTS

I've been thinking about how technical communicators add value to documents.

Writing is not typing! It's a lot more than that. But if all we do is 
reformat specs, we add little value. There are many other ways to add value 
to documents, both printed and online. I list ten areas below in order of 
increasing value. This is a somewhat idealized list; not all of us do all 
these things equally well. What can you add to this list?

Formatting: Applying a template provides at least minimal value, by making 
the information easier to find and grasp visually.

Editing: We convert written input to clear, concise, unambiguous, active 
English, and verify the information provided. (In companies without a QA 
group, verification is much more valuable.)

Translation to user terminology: Engineers naturally tend to create new terms 
to describe their products ("stringification," anyone?); we seek 
common-language equivalents. This translation to everyday language makes the 
products and their underlying concepts easier for lay audiences to grasp.

Organization: We decide the order in which information is presented: Not 
following the menu bar, but by importance, time sequence, or progressive 
disclosure. We know when to leave the details for later.

Level of detail: We decide the "atomicity" of descriptions and tasks based on 
the needs of the intended audience, not the expertise of the SME.

Examples: For many users, examples are the most important element of 
documentation. Creating working examples (which requires exercising the 
product) demonstrates our grasp of the product and adds significant value.

Illustrations and tables: I once replaced 22 pages of engineering description 
with one page of text and one flowchart. We know what to illustrate (not just 
screen shots, but also process flows, relationships, and completed screens), 
when to break up blocks of text, how to tie illustrations to text, and how to 
depict items cleanly without distracting the eye from the message.

Task-based presentation: Specs are necessarily product-based; that is, they 
describe the product and its components. (We call this reference 
information.) While it's easiest for us to bang out reference information, a 
user trying to perform a task has to map the functions described to the 
results desired. Task-based, or procedural, documentation does this work for 
users.

Synthesis of product requirements and product specifications: Marketing tells 
us what users want; Engineering tells us what the product does. We can 
combine this information, and tell users not only what the product does, but 
how it can solve their problems--which, when all is said and done, is the 
only reason they bought the product in the first place.

Troubleshooting: Engineers focus on how the product works; we can add what to 
do when the product doesn't work. Ask any user what part of the user's guide 
they turn to most, and the answer is likely to be the troubleshooting 
chapter. I believe this is the most difficult information to obtain, but the 
most valuable. The best source of troubleshooting information is the 
technical support group. Sometimes you have to wait several releases to get 
it, but good troubleshooting information, especially solutions to common 
problems, is almost beyond value.

          -- Steve

Steven Jong, Documentation Team Manager (Typo? What tpyo?)
Lightbridge, Inc., 67 South Bedford St., Burlington, MA 01803 USA
mailto:jong -at- lightbridge -dot- com -dot- nospam          781.359.4902 [voice]
Home Sweet Homepage: http://hometown.aol.com/SteveFJong

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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

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.  http://ieeepcs.org/2001/

---
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 
http://www.raycomm.com/techwhirl/ for more resources and info.