Technical Writing Tips – April 2016

We’ve covered a legion of topics on technical know-how in the last few years. To sum it up in one sentence, try rebooting your computer when it breaks.

Now that we’ve gotten that out of the way, let’s discuss a topic that, while technical, doesn’t test your ability to troubleshoot a computer. The subject causes fear in many of us when we hear terms such as dangling participle, predicate, or prepositional phrase. Any task requiring you to write, from a simple email to a major grant proposal, requires your best shot at technical writing.

Just as it took some time for Captain Ahab to hunt down the great white whale, you will need to spend some time in pursuit of technical writing proficiency. We expect in all cases that your success at writing will be much higher than Ahab’s quest for Moby Dick. Most of us write the way we learned, and to change bad habits for good ones requires significant effort and practice. Below are a few tips that will improve your writing without requiring an English degree:

(1) Write plain. Did you have any trouble understanding that last sentence, or miss a word? I would hope not, unless you’re skimming the article on a lunch break. Consider the following sentences:

Jon, clumsy as a three-legged dog, arced toward the ground in a snarl of limbs, a string of epithets erupting from his lips on the way down to turn even the most veteran soldier’s ears red.

Jon stumbled and cursed.

If you aim to be proficient in purple prose, the first sentence might do. If you want readers to understand Jon’s clumsiness, try the second sentence. If the second sentence conveys a clear message to the reader, go with it.

(2) Make descriptions count. Choose powerful nouns, verbs, and adjectives to describe your intent. Lose the adverbs. Adverbs modify an adjective, verb, other adverb, or word group. Which sentence below seems more powerful?

Tom very swiftly ran to the train, hastily jumping off the platform and through the closing door.

Tom sprinted to the train and leapt off the platform through the half-open door.

To explain, what might work better than very swiftly ran? If someone is running, we hope they are are moving swiftly, unless they look like me trying to jog. While the word ‘run’ would suffice, it may induce yawns in the reader. Sprint is an exciting word that conveys our meaning. The same goes for hastily jumping. Is there any other way to jump? Not in earth’s gravity. The word leap signifies taking a chance. Use stronger words that convey exact meaning. Give the reader less to parse. He or she will thank you for it.

Adverbs are not all bad; they are part of English for a reason. You can use adverbs to great effect when they reinforce a meaning opposite of the word you are modifying. Gracefully tripped, happily jeered, and smiled sadly are three examples; if a single word in the English language doesn’t exist to convey your irony, adverbs may help. In technical writing, you may find this technique less useful.

I repeat: ditch the adverbs.

(3) Don’t use slang. What if someone needs to translate your work to a different language? Acronyms and jargon may not translate well. Even within an industry, terms and phrases may differ by region. If a document restricts you to a certain word count, but you need to explain an acronym, try tip one and two.

(4) Use active voice. Stop using passive voice. Passive voice describes turning the subject of a sentence into the object. It makes your writing weaker. Look at the following examples:

Passive Voice: The mighty whale was harpooned  by Captain Ahab.

Active Voice: Captain Ahab harpooned the mighty whale.

Read a famous example of passive voice in Ronald Reagan’s non-apology speech for the Iran-Contra affair. Is it ever appropriate to use the passive voice? Yes – when you want to show an action happening to a subject.  Instead of the active Someone destroyed my flowerbed you might try My begonias were massacred with a garden rake.

Remember that each tip listed above is a not a rule. While you’ll do well to exercise them in your writing, don’t be Captain Ahab and go overboard. I’ve used a number of examples as they relate to fiction and non-fiction writing which also apply to technical writing. By eliminating fluff and sharpening your word sword, you better your chances of impaling the reader with meaning.