With that title to this post, and this Baby Blues comic, I hardly need to say more…

Displaying

…but I will: If you write instructions, always test them.

Subscribe to this blog's RSS feed

The Fifth Rule

rogersgeorge on November 19th, 2016

I’m going to skip the fourth of my five gold rules (Be Complete) for the moment because I have a good example for the fifth rule, Be Useful.

A lot of documents have two readerships, some entity that makes rules about the writing, and the people the document is intended for. For example, a. an Army manual has to conform to the Army’s style guide, but b. it’s aimed at the soldier who needs the information in the manual. Bank IT documentation has to a. demonstrate that the bank is being responsible in its development of software that handles your money (iow the auditors like it), and b. it has to describe the part of the project that it’s about, such as requirements. Say you have to write a term paper. The teacher might a. specify things like length and topic, and maybe a style guide to follow. And b. you want also to make the paper an interesting read that says something appropriate about the subject.

Forget about the a. category for now. You can’t control that. But the b. category is the actual content, and usefulness is key.

Recently my DSW (dear sweet wife) asked me to write some instructions about how to operate our wood stove for people who aren’t sure how to make it go. So I wrote up a nice set of instructions; where to set the controls, how to build the fire, and how to keep it going. Here’s a little of it:

  1. Turn the lever at the top left so it points up. This bypasses the catalytic unit and speeds the draft a little. (Rotate the lever up and down to get a feel for it.)
  2. Turn the lever on the top right toward you. This opens the draft.
  3. Open the glass doors all the way. They tend to get in your way if you open them part way.
  4. Put in a baseball-size wad of paper. Don’t use magazine paper.
  5. Stack a generous handful or two of the smallest wood you can find on the paper. Pencil diameter and smaller.

Seems okay, right? The whole thing took a little less than a page. Since my youngest was a likely user of this information, I gave it to her to read. She read several lines and castigated me, in detail, for patronizing her, and for using the word “catalytic,” which she didn’t care about, and she tossed it back to me. Not very tactful or friendly (hey, she’s 17), but I’m a professional, so I took the information, not the approach, to heart, and produced something in line with what she actually needed:

Woodstove Levers

Top right: Toward you to start a fire.
                   Away to keep the fire from getting too hot, and when you put in wood.

Top left:Up when starting the fire.
               Down after the fire has lots of coals.

Bottom right: Keep it shut unless you’re cleaning out the ashes.

That’s all that was necessary, a cheat sheet.

When you write, consider what your readership needs, and stick to that. It’s the information, not the words, that are valuable.

Interesting use of “technical writer”

rogersgeorge on November 29th, 2013

A recent article in The Register criticized Google’s Eric Schmidt for, among other things, his (lack of) ability as a technical writer. Since this blog is mainly about expository writing, of which technical writing is a subset, I feel a need to share. Here’s the passage I’m referring to:

…Schmidt goes on to show he’s not conversant with the gentle art of technical writing with procedures that use inconsistent verbs, fail to open each step of a procedure with an active verb and make assumptions that lead to user-befuddling ambiguities.

Gentle art, eh? I’m flattered. Eric’s instructions are too long to quote here (you can find a link them in the article), but the criticisms mentioned in the quote above are worth noting for your own writing.

Inconsistent verbs…active verb. I’m not sure what the writer is referring to here, but when you write instructions, you should use the imperative. Do not say “Please.” Give one instruction per step. Tell the result of following the instruction correctly. (Do not write the result as a separate step!)

User-befuddling ambiguities. Ambiguity is the bane of technical writing. You should write so your material is interpreted exactly one way. Have someone follow your instructions. If they get something wrong, fix the writing. Do not whack the person upside the head for being stupid.

Tech writing has a lot more features, and I saw several other tech writing mistakes in Eric’s material, but I won’t go into them here.

Now in Eric’s defense, he is not a technical writer. He’s an extremely successful businessman with lots of money. (Warning: shameless plug ahead) If his intent is to write a good set of instructions (and not a marketing piece disguised as tech writing) maybe he should hire (ahem) a good technical writer to write the instructions for him.

Google's Eric Schmidt

Eric Schmidt. Image credit: AP

Old instructions

rogersgeorge on April 7th, 2012

I’m not sure what approach to take on today’s topic.

Last week my brother (whom I hadn’t seen for maybe five years) and I visited the museum on the campus of the US Naval Academy. I was embarrassed at the poor quality of the writing  on many of the labels, but that’s a story for another post. One of the displays showed an instruction book for building a sailing ship. Here is a single sentence from the open page:

Some say the general method, which has been pitch’d upon by the greater number of shipwrights and others, and may be term’d shipwrights Hall Rule, is to take the length of the keel, measured from the back of the main post, to the fore-side of the stem, at the upper edge of the lower harping, by a perpendicular made from thence to the upper or lower edge of the keel, only 3/8 of the main breadth, from the outside of the plank of one side to the outside of the plank of the other side, at the broadest place of the ship, being set backward of aftward from the right angle made by such a perpendicular and base.

The intended readership was people in a skilled trade: shipwrights. No people with doctorates or fancy academic backgrounds here. The book contained illustrations, but not for this particular sentence. Think you could handle a whole book of this kind of writing? We built some pretty good sailing ships back then, too. Someone told me that the readership for The Federalist Papers, heavy reading forced on a few high school and college students, was New England farmers. I’m a bit concerned about the typical person’s reading and comprehension skills nowadays.

On the other hand, I celebrate that the technical writing trade has advanced to make even complex instructions (fairly) easy to understand, allowing people to concentrate on the task without having to spend a lot of effort deciphering the instructions. (One of my guidelines is that bad writing must not be justified with the excuse that the reader will figure it out.) After all, we build some pretty good spaceships and computers.

I’m not sayin’, I’m just sayin’.