Monthly Archives: May 2010

An Ordinance on Ordinals (The Procedure Series, Part 5)

In Anatomy of a Technical Procedure I listed the four key components of any technical procedure. Promises, Promises talked about the first one. Let’s ponder the next one, the numbered step. Any numbered step (or “step”) has these properties: It begins with a number. (The rare exception is the single-step procedure, which uses a bullet.) That is, it’s ordinal. It uses the imperative mood. The tone of the step is “Do this now.” It tells the user to do one action (“Click Print,”) or sometimes two (“Open the File menu, and click Print”), but never more. Perhaps the most overlooked and yet most important property of a step is its …

Continue reading

Posted in Uncategorized.

The World’s Most Badly Written Procedure

In the M*A*S*H episode “The Army-Navy Game,” Hawkeye and Trapper try to dismantle a ticking bomb parked in the middle of the compound, while Henry Blake calls out the bomb manufacturer’s instructions from a distance away. Allow me to paraphrase (I couldn’t find the script online): Henry: Clip the wires leading from the head of the bomb.Hawkeye and Trapper clip the wires.Henry: But first… That’s just an extreme (and riotous) example of why the order of steps in a procedure counts. Um, er, I mean, matters. In the next post of the Procedure Series, I’ll explain more.

Posted in Uncategorized.

Promises, Promises: (The Procedure Series, Part 4)

I mentioned in “Procedures Abound” that procedures always make an implicit or explicit promise to the user–the promise that if the user completes the steps, she’ll get what she wants: a new document, a credit report, a greener environment, bigger hair, whatever. The promise says, “If you do these things, you’ll get this thing.” The procedures we come across every day often use implicit promises. For example, the fact that the instructions “Lather. Rinse. Repeat” appear on the back of a shampoo bottle implies that following these instructions with the contents of the bottle will give you clean hair. In a cookbook, a list of ingredients and a set of …

Continue reading

Posted in Uncategorized.

Anatomy of a Technical Procedure (The Procedure Series, Part 3)

In my most recent post of the Procedure Series, I promised to dissect a technical procedure bit by exacting bit. To the right is one I wrote as an example. Good, clean fun, no? The key to understanding the procedure and writing it well is understanding its anatomy. Here are the major parts: The procedure statement (the “promise”) Numerical steps Feedback statements (with or without graphics) Optional Note, Caution, Tip, or Warning statements In the next few posts, I’ll overanalyze each of these to explain their usage and functions. In the meantime, see if you can spot the elements I just mentioned in my example to the right. And if …

Continue reading

Posted in Uncategorized.

Somewhere in Nogales, Arizona

A friend and I went tooling around southeastern Arizona last weekend, looking for the artists’ colony (and minor tourist trap) called Tubac. My friend had a new GPS system, and not wanting to rely entirely on her MapQuest directions, we looked up the town of Tubac en route. Eventually we found it under “Attractions,” and we arrived in time for lunch. (Tubac is lovely, if hot, this time of year. I recommend a visit if you’re in the area. But I digress.) On the way home, we decided the GPS could lead us safely through Nogales, a border town with old streets and signs that post mileage in kilometers. We …

Continue reading

Posted in Uncategorized.

Procedures Abound (The Procedure Series, Part 2)

In Lather. Rinse. Repeat I described a working woman’s typical day and the random procedures she encountered throughout that day. In this post, let’s pick out the 15 procedures and explain why they are procedures. Here they are: Instructions on the shampoo bottle (1) Instructions on the medicine bottle (1) The six stoplights and one Stop sign (7) The instructions on the card reader at the office building (1) The Yoga class (1) The instructions on the display of the POS machine at the grocery store (1) The recipe used to cook dinner (1) The pattern used to make the quilt (1) The news story about protecting personal credit from …

Continue reading

Posted in Uncategorized.

An Occupational Hazard

If you enjoy the writing part of your job at all, it’s probably because you like writing in general. And if you like writing in general, you probably like reading. And if you’re a writer who likes reading, you probably notice when someone’s writing is, shall we say, sub-standard. I’m not talking about other tech writers and their work. Bad tech writing litters the high-tech landscape; Bad tech writing abounds. I’m talking about the work of what some (but not me) would call “real” writers: People who write memoirs, books about industry, fiction. People who are published. People who should, in theory, know better. (An aside: I myself don’t call …

Continue reading

Posted in Uncategorized.