The place to learn about your Mac. Tips and tutorials for novices and experts.

Effective Technical Writing


This article was originally submitted to coach tutorial contest contestants. We liked it so much that we've left it online -- hopefully it will help other writers.

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.


    • Meet Your Macinstructor

      Adam C. Engst is the publisher of TidBITS, one of the oldest and most-respected Internet-based newsletters, distributed weekly to tens of thousands of readers. He has written numerous technical books, including the best-selling Internet Starter Kit series, and many magazine articles - thanks to Contributing Editor positions at MacUser, MacWEEK, and now Macworld.


 
                          





Copyright © 2016 Macinstruct. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.