Effective Technical Writing

  Adam Engst       January 31, 2007      Tutorials Education

Greetings, writerly ones! I’ve been asked to offer you some sage advice, but since holiday preparations have left me rather short on thyme, I’ll settle for these recommendations for effective technical writing.

First, and most important, write directly to your reader, and write in the active voice. There is little more boring than the passive voice, though I’d award bonus points to anyone who could pull off the passive-aggressive voice without it becoming annoying. Writing directly to the reader can involve using the first person as I’ve done here, but you must certainly speak in the second person.

Second, if you’re going to use a “First,” you must follow it with a “Second.” The corollary to this rule is to be careful about your outline; just as every First must have a Second, every heading must have at least two sub-headings. Your seventh grade English teacher will thank you, as will readers who are subconsciously more able to follow your instructions thanks to the logical structure.

If you don’t remember your seventh grade English teacher, think harder. That’s because good writing really does require a strong adherence to the basics. Spelling, grammar, and punctuation are all important, and while some may argue that that’s what editors are for, I would counter that editors prefer to focus on the content of your writing, rather than wasting time fixing your seventh grade mistakes.

Mix it up! That’s right - fisticuffs. With your word choice and sentence structures. Too much technical writing becomes mired in a tarry pit of repetitive wording and stale subject-verb-object sentences. Be sure to exercise caution, though. I learned long ago that when I’m editing, even in my own writing, I tend to pick up and reuse clever words elsewhere on the visible page. A trenchant term or turn of a phrase works wonders, but only once in an article or book chapter.

Don’t be afraid to let your speech patterns inform your writing. I often read what I’ve written out loud (well, under my breath, anyway), to make sure it sounds like something I’d say. Often, when a sentence sounds funny to my ears, a closer look reveals a subtle mistake or confusion as well. Writing as you would speak, or at least as you’d like to speak if you were scripting yourself, will make your text flow more smoothly for readers as well, keeping them interested and learning.

With that, I must dash, but let me leave you with a few entirely unrelated thoughts that I’ve learned over the years:

• Writing short is much harder than writing long.
• If you agree to write about an application that’s being developed, prepare to become a software tester and interface designer as well.
• When communicating with colleagues, finding something positive to say, even when you must bear bad news, will make life much easier.
• If you commit to a deadline, meet it. No ifs, ands, or buts. Just meet it. Editors will love you for it.