Technical writing ... a short course

In my new position I get to review software design documents created by people in our work unit. Our project is integrating information from diverse software applications to provide my company a unified view of the crude oil and products trading that we do. We're merging data from the trading system itself, from a credit management system (really important in the current economic situation) and from a pricing/risk system. That last one's particularly interesting because it attempts to keep the Company from going bankrupt because it bought too much oil when prices were high or sold too much when prices were low. Complicated stuff.

We have to pass information back and forth between those three systems. Plus each of those three pushes and pulls data from more than twenty "outside" systems. For example, we have to send accounting information about the trades to the Company's accounting system monthly. We also pull in externally-created financial statements and credit reports for our suppliers and customers. It's nice to know that we'll actually get paid when the time comes, so we check that stuff pretty carefully.

The only way to pass that information around is to write computer programs to extract the information from one system, massage it, and then pass that information to the receiving system. For each one of those interfaces (on the order of 100, by the time everything's said and done), we need to write a document describing what we're going to do. The business people read the document and say, "Yup, that's what we need." The programmers read the document and say, "OK, I understand what software you want me to write."

Part of my job is to read each of those documents. I verify that the described solution appears to work. I verify that the solution adheres to our software architectural standards. I verify that the document contains all the information that a programmer is going to need to get busy in a few months and actually write the software.

It's driving me crazy.

My dad was a writer. I remember being in tears when I was in grade and even high school after I'd take some piece of writing to my father. I'd have spent probably an hour laboriously typing on a manual typewriter the single page that the assignment required. I'd be pretty proud of it. Dad would look at it, look at me, and then start in. "This isn't clear. Make this shorter. You can say this better. ..." It never failed. No matter how good I thought it was, it wasn't. I'd have to look at retyping the whole thing. (White-outs were never enough to correct the mistakes he found.) It was painful and only more so because ... damn it ... he was right. Everything he suggested improved the piece.

So now I'm the reviewer. Most of the team doing the writing don't come from a liberal arts background, and in fact not a US background of any kind. They are dyed in the wool techies. They need help. So, for posterity, here are my rules for technical writing:

All things being equal, shorter is better.

Figure out who your audience is before you start. Don't put anything in the document that your audience won't use. When you try to include it, don't tell me "Oh, that's good information." It's not good if no one's going to use it.

Use the journalistic pyramid style: start simple, get more detailed as you go. That way, when the reader has reached the level of detail he or she needs or desires, the reader just stops reading.

If a sentence contains any of these words then you probably need to rewrite it: "is", "are", "be". Those are tipoffs that you're writing in passive voice and it drives me crazy. E.g., "It is sent to program two." WHO or WHAT sends it to the program? Don't compound the problem by saying "It is sent to program two by program one." Say: "Program one sends it to program two." It saves two words: 22%. It saves five characters: 12%. You end up writing 9 pages instead of 10 and the 9 are much more clear and readable.

Write everything in present tense. If something's not happened yet, pretend it has. You're writing about something you want to make happen. Be positive.

Don't try to impress with how smart you are. Never use two syllables when one will do.

Put things in the document or in an appendix, but not both. That way if something changes you don't have to make two updates to the document, one of which you're bound to forget.

Look for chances to use the imperative sentence. That style is short and clear. Do it.

Whew. It's good to vent.