Ten ways technical communicators add value to documents (long)

Subject: Ten ways technical communicators add value to documents (long)
From: SteveFJong -at- aol -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 28 Oct 2000 18:06:56 EDT

The recent thread on whether we're more than glorified secretaries set me to
thinking about how technical communicators add value to documents.

Writing is not typing! It's a lot more than that. But we have to invest
effort into our work. If all we do is reformat specs, we add little value,
and in those situations engineers are right to belittle our skills. But there
are many other areas where we add value to the documents, both printed and
online. I list the areas below in order of increasing value. This is a
somewhat idealized list; not all of us do all these things equally well. But
virtually no engineer is even conversant with all these concepts, much less
willing to implement them in specifications. 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.

Editorial: We convert written input to clear, concise, unambiguous, active
English, and verify the information provided. (in organizations without a QA
function, verification becomes much more valuable.)

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

Organization: We decide the order in which information is presented: not
left-to-right across the menu bar, but by importance, or time sequence, or by
progressive disclosure. The first thing the user does is log in; the first
step the database administrator makes is to size the disk to the database. 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. (We have a
conversation going on at work over database administration. Should tasks go
step-by-step, or should we refer users to the Oracle documentation to avoid
redundancy? We know how to do it either way, but I say find out what the
intended audience wants. Well, Oracle says 80% of the errors made by
sysadmins come from lack of training. I think we should include those steps!)

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: A picture is worth not one but ten thousand words.
I once replaced 22 pages of engineering description with one page of text and
one flowchart. We know what to illustrate (process flows, relationships,
completed screens--not just screen shots, hardware parts), 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.
(Oh, you want to scan a photo? That's the RENDER command--I'm surprised you
couldn't find it 8^) 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://members.aol.com/SteveFJong

Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Your web site localized into 32 languages? Maybe not now, but sooner than
you think. Download ForeignExchange's FREE paper, "3 steps to successful
translation management" at http://www.fxtrans.com/3steps.html?tw.

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.

Previous by Author: In defense of 7 +/-2 steps per procedure
Next by Author: Window size/placement in RoboHelp
Previous by Thread: Re: Associating PDF with Acrobat Reader
Next by Thread: UPDATE - Friendly Faces of TECHWR-L

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

Sponsored Ads