|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.|
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!
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
As you can see, the USE strategy produces the best karma, at least for the technical writer. Let me explain how to use USE.
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.
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.
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
August 26, 2002