G+G logo   Gordon & Gordon is a partnership of two award-winning writers who specialize in high-technology, Manuel Gordon and Gordon Graham. Our clients hire us to explain complex products and to persuade demanding customers. We also share our many years of experience through practical, cost-effective consulting and training.  


TECHNICAL WRITING

MARKETING WRITING

WORKSHOPS

WORKBOOKS

DVDs

SUCCESS STORIES

USEFUL IDEAS

DOWNLOADS

ABOUT US

CLIENT LIST

AWARDS

CONTACT US

SITE MAP

SEARCH

HOME
     
Understand, Simplify, and Explain
Technical Writers Must U.S.E. Information

by Manuel Gordon

There's that magic moment at the start of many a software documentation project: listen!

Thunk.

That's it. The sound of a nice, fat, functional specification hitting your desk. As you leaf through it, a special feeling comes over you, a mixture of panic and despair, and the certain knowledge that if you live to be 120 years old, you will never, ever understand it.

"Useless information," a wise old editor told me once, "is always written at great length. And with an abundance of diagrams."

How should you, as a technical writer working on a manual, treat information that you do not understand? Table 1 illustrates some of the strategies I have encountered.

Table 1: Strategies for Dealing with Complex Information

Reasoning Strategy Results
"I don't understand it, so it can't be important." Cut it. A short first draft. Long, stormy meetings with developers. The manual is shipped to customers, where it is never heard from again.
"I don't understand it, so it must be very important." Gently comb through the fine, silken web of tangled prose, carefully correcting any errors of syntax, while retaining all the ambiguity, imprecision, spelling errors, and capital letters. Then import the text into FrameMaker. When the developers review your drafts, they only correct the spelling errors that you added. You meet your deadlines with ease. The manual is shipped to customers, where it is never heard from again.
"I'm a technical writer. I should only write about what I know."
  • Understand
  • Simplify
  • Explain
Long, fruitful meetings with developers. You meet your deadlines with difficulty. You take great pride in your work. The manual is shipped to customers, where it is never heard from again.

As you can see, the USE strategy produces the best karma, at least for the technical writer. Let me explain how to use USE.

Understand

You don't need to completely understand the functional spec. The developers did not write it for you. They certainly didn't write it for the users. They wrote it for themselves.

Read the functional spec, and try to figure out what the software looks like to the users. Draw up a list of questions for the developers. Take the spec to meetings with the developers: they like to see their work treated with respect. Ask questions until your head is about to explode, then set a date for the next meeting. Read the spec again. Repeat until you understand what parts, if any, of the spec you need to understand.

Simplify

The diagrams in the spec are quite impressive, with circles and labels and boxes within boxes, and arrows going every which way. When you meet with the developers, they will draw you more diagrams on the whiteboard, this time without the labels. Figure out which circles and boxes are "visible" to your users, and ignore the rest. Use the same approach with the text.

Explain

When you meet with developers, explain their system back to them in your own words. If you make a mistake, listen, and then try again. Repeat until they smile.

When you start writing, begin with a blank document. Don't start by revising the spec. Be bold: explain the software in your own words. Draw your diagrams from scratch. If you must use any material from the spec, cut and paste sparingly, then revise thoroughly.

And when people ask you what you do for a living, explain that you're a writer. A technical writer.


This article originally appeared in Connections, the newsletter of the STC Montreal chapter, and in Intercom, the magazine of the Society for Technical Communication.



How to Contact Us
 
Last updated:
August 26, 2002

Entire contents
© 1999-2006
by Manuel Gordon
& Gordon Graham

TO TOP

 

   
small photo of Manny
 

How to reach Manuel Gordon

Tel: (514) 934-3274

Fax: (514) 934-6077

Email: manuel@gordonandgordon.com

small photo of GG

  How to reach Gordon Graham

Tel: (705) 842-2428 Eastern

Fax: (705) 842-2429

Email: gordon@gordonandgordon.com