How to Write Tech Stuff Really Good

  Robin Williams       January 23, 2007      Tutorials Education

Be active.

This is passive: In case of emergency, the red button should be pressed.
This is active: In case of emergency, hit the red button.

Passive is good only when you don’t want to hold anyone responsible: There was a red button pressed this morning.

Active puts the responsibility squarely on someone: Jane hit the red button this morning.

In writing tech material, you need to be responsible and you need to make your reader feel responsible. Get rid of mushy passive stuff. One easy way to write in the active voice is to avoid gerunds (“ings”). Most words that end in “ing” are passive.

Passive (no one is responsible)
One’s options include:

• Obtaining a list of people.
• Using a UNIX command called finger.
• Accessing a knowbot via telnet.
• Using Netfind.

Active (the reader is responsible)
You can:

• Obtain a list of people.
• Use a UNIX command called “finger.”
• Access a knowbot via telnet.
• Use Netfind.

Be brief.

You might be surprised how many superfluous words you can delete from a sentence. And usually you’ll find it’s more direct and makes more sense.

Wordy: If a quote in text goes longer than three lines, you should make a separate paragraph.
Brief: If a quote is longer than three lines, make a separate paragraph.

Wordy: What’s called tracking in desktop publishing programs is eliminating or adding the same user-specified amount of letterspacing between each character.
Brief: “Tracking” adds or deletes a uniform amount of space between the letters in a range of text. (I eliminated “in desktop pubishing programs” because that’s what the whole book is about.)

BUT use as many words as are necessary to make things clear, even if that means adding some words. In the example below (3a), the bad example uses 11 words, and the better example uses 13. The trick is to get rid of the useless words.

Be clear.

a. Put things in the right order. Please don’t tell me: Choose “Line break” from the “Insert” command in the Edit menu. Start with what I have to do first: From the Edit menu, slide down to “Insert” and then choose “Line break.”

b. Tell me what I’m going to do before I start. Please don’t tell me: Hold down the Shift and Command keys, put your left foot on the desk, cross your eyes, and howl like a banshee to make a fool of yourself.

Instead: To make a fool of yourself, hold down the Shift and Command keys, put your left foot on the desk, cross your eyes, and howl like a banshee.

Be honest.

Don’t pretend you know things you don’t. Don’t try to get by with an explanation that you don’t really understand yourself. Don’t write directions while thinking to yourself, “I’m pretty sure this will work.” Find out what’s right and write it. Be true and honest with your readers so they learn to trust your work.

Be real.

Tech stuff is difficult enough—don’t make it more difficult by pretending to be anything other than who you are. I’ve had co-writers try to emulate my style. I don’t even know what my style is, but they seem to think it’s lighthearted and fun and humorous and so they go overboard trying really hard to be . . . something, I don’t know what. I’ve never had an intention to make things lighthearted and fun and humorous – I really don’t know what people are laughing at in my books. They’re not funny. I just write honestly and with a clear motivation to make it understandable and I don’t try to be all stuffy or highfalutin or act like a Mac Priest. It’s just me. Trust that being just you is perfectly great.

Personally, I firmly believe that how tech material appears on the page is just as critical to a reader’s understanding as what it says. But that’s another article. ;-)