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.