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

How to be a Fabulous Technical Writer


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.

Everything you need to know in order be a great technical writer can be summed up in a recent conversation between an adult and my eight-year-old son, Tristan:

Tristan: How do you put a hippopotamus in the refrigerator?
Guest: I don't know.
Tristan: Open the door and stuff it in.
Guest: Ah.

Tristan: How do you put a giraffe in the refrigerator?
Guest: Ah hah! Open the door and stuff it in.
Tristan: No! Open the door, and take out the hippopotamus; then stuff in the giraffe.
Guest: Laughter.

If an eight-year-old can do it, then you can too. The three principles of awesome tech writing are:

  1. Tell your reader exactly what to do, in exactly the right order. If there isn't room for two wild animals in the fridge, be sure to tell the reader to take out the first one before adding the second. More specific to the field of computer writing, never tell a reader to "click" a checkbox, since you can't anticipate whether the checkbox is already checked. Most importantly, never write something like "to turn on the ObscureFeature, check the ObscureFeature box." This information is obvious to anyone looking casually at the dialog, but it skips over the fact that nobody knows what the feature does, not the reader, not the writer, and - quite possibly - not even the software's developer.

    To succeed at this sometimes-Herculean task, you should refer to elements in the interface in a consistent way, use the excellent grammar skills that you learned in high school (if your grammar stinks, your imprecise writing will drive your editor bananas), and be sure to work through the steps yourself to verify that they work.

  2. Unless you are writing for a large organization and want your writing to sound like it was approved by a committee - and, yes, I know that some excellent tech writers have jobs like these, I did once - let your hair down and show your personality in your writing. Humor is always more effective than being bossy or, worse, than being boring.
  3. Use a speeling chucker.



Meet Your Macinstructor

Tonya Engst worked for Cornell University and Microsoft Corporation in the early years of her career. She co-founded TidBITS, an email newsletter and Web site about the Mac, in 1990 with her now-husband, Adam Engst. She also co-founded the Take Control books series about computer topics, again with Adam Engst, in 2003, and she currently works as editor in chief for the series. You can find her online at http://www.tidbits.com/tonya/


 
                          





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