Lather. Rinse. Repeat. (The Procedure Series, Part 1)

Karen Field CarrollUncategorizedLeave a Comment

When you think of the word “procedure,” you probably think of attorneys following courtroom etiquette or your HR department’s stuffy “Policies and Procedures” documentation. If you’re a tech writer, you might also think of the instructions you write every day. (“1. Click the File menu. 2. Click Print.”)

A procedure, or a set of instructions, is all of those things, according to Merriam-Webster. But it’s much more, too.

In fact, what you probably don’t realize is that you come across procedures all day long, every day. To see what I mean, read my fictional account of one woman’s typical day. See if you can spot the procedures our heroine encounters.

A Day in the Life
On workdays, a woman named Cheryl wakes up at 6:30, the alarm clock jarring her from sleep. This morning is no different. Slamming the alarm clock into silence, she staggers into the shower, where she washes her hair using a new, “organic” shampoo. Because she’s never used the product before, she reads the directions first, squinting through the water running down her face. She’s not surprised to find the obligatory “Lather. Rinse. Repeat,” on the back of the bottle.

Clean and dry, she brushes her teeth and takes her asthma medication. Again, it’s a new prescription, so she reads the label: “Take one dose twice daily.”

Kissing her husband good-bye, Cheryl hops into her Ford Escape and starts the engine, noticing that the display has a message for her: “Change oil soon.”

On the way to work, Cheryl encounters six stoplights (four red, two green), and one Stop sign. Parking her car in the office parking lot, she gathers her things (including her access card) and walks up to the building. At the door, she obeys the first sentence on a sign that reads, “Slide card. For assistance, go to the lobby,” and enters the building.

At lunch she takes a yoga class, following her instructor’s commands through a Sun Salutation series. The instructor tells her to, “Come into Downward Dog position,” and “Move into Plank position.” Cheryl follows dutifully.

On her way home from work, Cheryl stops at the grocery store. She picks up milk, Shredded Wheat, leafy green lettuce, a bottle of Chardonnay, and a 12-pack of Diet Pepsi. To check out, she stands in the line marked “Ten items or less.” At the POS machine of the checkout counter, she slides her credit card through the slot. When the machine display reads, “Enter your PIN for debit, or press Cancel for credit,” she presses Cancel and finishes the transaction.

Once home, she cooks dinner for herself and her husband using a recipe for chicken in wine sauce. After dinner she cleans up the dishes and wanders into her craft room to start working on a quilt for her new nephew. She reads the quilt pattern closely, making sure she cuts up the fabric according to the stated dimensions. About 11pm she watches the news with her husband, noting a story about how to protect her credit from identity thieves. Then she sets the alarm for 6:30 am and falls into a comfortable sleep.

Procedures, Procedures Everywhere…
Did you find the procedures? As you hunt for them, remember that procedures always….

  • Lead the follower to a specific, discrete goal.
  • Make a promise (explicitly or implicitly) that following the procedure leads to that goal.
  • Use the imperative mood.
  • Include one or more command statements.
  • Appear in graphical, audible, or verbal form, or some combination of these.

(Next time, I’ll point out the procedures in our little narrative—there are 15, counting the entire yoga class as one–and explain what makes them procedures. After that, we’ll side-shift into talking about the procedures technical writers most often write.)

Yes, It Matters

Tech writers are prone to thinking that our work doesn’t matter, that nobody reads it. By culling information about procedures from everyday life, I wanted you to see that what we write does matter. Even if we don’t write the recipes in the cookbook or the steps in the display of the POS machine, we set the standard for people who do.

And isn’t it amazing that a procedure can be as long and complicated as one written for installing a satellite dish, for example, or as simple, as laconic, and even as elegant as “Lather. Rinse. Repeat.”

It’s a Process

Karen Field CarrollUncategorizedLeave a Comment

Have you ever noticed how often we follow a process to get something done? Whether it’s tying our shoes or shopping for groceries, the process–that is, the series of steps, or the procedure we use to do it–is the journey that takes us from the start of the task to the end.

When I clean the kitchen, for example, the first thing I do is run hot sudsy water in the sink. Then I grab the microwave plate, the coffee pot, and the spoon rest I keep by the stove and put them in the sink to soak. Next I wipe down the counter tops, clean inside the microwave, polish the stainless steel, empty the sink and dry its contents, wash out the pet dishes, and spray and scrub down the sink. Last I sweep and mop the floors. The whole endeavor takes about an hour, and it’s not a chore I look forward to. But when I’m in the middle of it, when I’m scrubbing Piper’s food dish free of its doggy drool or pulling the trash compactor out from the wall to sweep behind it, I fall into an easy rhythm. I let my mind wander, and I take comfort in knowing what to do next, and what to do after that. I like being in the middle of a process, and I like knowing that process will help me meet my goal (in this case, a clean kitchen).

I’ve cleaned this kitchen roughly 12 times since we bought our house six months ago. At first, I felt overwhelmed. Everything was different from the kitchen in our old rental: The oven is on the opposite side of the sink; the stove has a ceramic cooktop instead of gas burners; the refrigerator is a freezer-on-top instead of a side-by-side. But with practice, I’ve broken the chore into ordered steps. I know, for example, that I have to clean the sink after I soak the miscellany, not before, because the soaking dirties the sink. A no-brainer? Probably. But it’s something I like knowing. I like having a procedure and following it.

Maybe that’s why I like writing technical documents so much. My beloved procedure is at the heart of almost any document a user needs. And a good tech writer is a writer who respects the procedure’s use, and its usefulness. Anyone who teaches–and technical writing is a form of teaching–must understand what makes a procedure a procedure, and what makes it work for the user.

Because I believe the procedure is the most important thing tech writers write, I’m dedicating a series of blog posts to it. I’ll answer questions about writing the procedure, such as, What are a procedure’s components? When should writers use the procedure? And I’ll probably swoon over it a little, too. (Have you ever noticed how many procedures we use in everyday life? Does “Lather. Rinse. Repeat.” sound familiar?) If you have something to add, I’d love to know what you’re thinking. We can encounter this vital and yet little-respected art form together.

We’ll begin by exploring the procedure in everyday life–the ordered, the purposeful, the utterly ubiquitous procedure. That’s next week’s topic.

Tech Writer Gets Exercised Over Elliptical Machine’s Manual

Karen Field CarrollUncategorizedLeave a Comment

My husband and I just bought an elliptical machine. I used to work in fitness centers, so I knew how to use the thing without reading the manual, but I read the manual anyway, just because I like to snoop around other tech writers’ user guides.

This tour through the manual proved instructive. No, I didn’t learn anything about how to use the elliptical machine, but I did learn something about writing procedures.

Consider this sentence, which appears below a diagram of the elliptical machine in the manual:

The crank arms can turn in either direction. It is recommended that you turn the crank arms in the direction shown by the arrow; however, for variety you can turn the crank arms in the opposite direction.

Inspecting the diagram told me that the “crank arms” are the rods that run from the pedals to the flywheel casing. Further inspection showed me that the “direction shown by the arrow” is clockwise, and that the “opposite direction” is counterclockwise. Even further inspection showed me that the pedals move forward when the crank arms move in this clockwise direction. Which means they move backward when the crank arms move counterclockwise. Then I deduced that the pedals move the crank arms, not the other way around. So, I concluded that I could make the crank arms turn clockwise by pedaling forward, and I could make the crank arm turn counterclockwise by pedaling backward. But pedaling backward is not recommended. Conclusion: I should pedal forward most of the time during my workout.

After reading this, however, I was so exhausted I didn’t need a workout anymore.

So instead, I analyzed the writing. As a user, especially one who is familiar with the product already, why did I have to work so hard to understand something as simple as “pedal forward”? I think the tech writer made several mistakes in these instructions, which I’ve broken down phrase by awful phrase here:

The crank arms can turn in either direction…

Here, the writer (let’s call him George) writes about the product, not to the user. He uses system terms (“crank arms”) and not user terms (“the pedals”). He asks the user to leap the chasm between her goal (getting a workout) and his understanding of the product.

It is recommended….

My question: Who recommends this? The company? The fitness industry? And why do they recommend it? What happens if I turn the crank arms the other way (or pedal backward)? Is it unsafe to pedal this way? Does pedaling backward wear out the machine’s parts faster than pedaling forward? Will I get a less effective workout if I pedal backward instead of forward? If the writer couldn’t tell me why one action is recommended over another, I can’t determine how important this caution really is.

…that you turn the crank arms….

Here George uses an abstraction to explain what the user does. When I first read this sentence, I pictured myself grasping the crank arms with my hand and turning them. It baffled me.

…in the direction shown by the arrow….

George does something that I think no writer should ever do: He relies on an image to explain the text. What if someone were reading the instructions to me? What if I were using optical character recognition software to read the manual? The point is, if I couldn’t see the graphic, I’d have no idea what direction the text refers to.

(Writers can and should use graphics to complement the text, or to reinforce a concept in it. But we should not let the graphic alone do the explaining.)

…however, for variety, you can turn the crank arms in the opposite direction.

Here George repeats his earlier mistakes and heaps on more. The term “for variety” is vague. It also implies a contradiction to the earlier recommendation. “Turning the crank arms” is, again, a third-degree way of saying “pedal backward.” “In the opposite direction” relies on the graphic to explain the text.

By now, you’ve probably figured out that I would have written the sentence this way: “For your safety, we recommend pedaling forward, not backward. If you pedal backward during your workout, do so with caution.”

(For the sake of the sample sentence, I assumed that George recommends pedaling forward because pedaling backwards in unsafe. I still have no idea why he really recommends pedaling forward.)

I think it was Nathaniel Hawthorne who once said, “Easy reading is damn hard writing.” Perhaps that sentiment applies to tech writing more than other types of writing.

In other words, even if some of the products we write about can give users a workout, the manuals we write to explain them shouldn’t.

Name Changer

Karen Field CarrollUncategorizedLeave a Comment

Ever since the STC started calling us tech writers “technical communicators,” I’ve been pondering the weight of our job titles. I realize the STC made the change to include those of us who do things in the field that are specific and unique, such as usability testing, graphics design, or tutorial publishing. Our field is as broad as any aspect of engineering, and it’s good that way. So I don’t mind the somewhat clunky “technical communicator” reference, especially if we use it only among our peers.

What disturbs me is the habit some technical writers have of spiffing up their own job titles. I’ve seen titles like “Information Products Engineer” and “Documents Designer” and “Information Specialist.”

In fact, the first time I heard a tech writer call herself an “information products designer,” I thought of the Honeymooners. Wasn’t it Ralph Kramden’s friend Ed who, as a sewer worker, called himself a “sanitation engineer”? It was funny, right? And why? Because we knew Ed was hiding his embarrassment about his work by polishing up his job title.

I suspect that’s what tech writers who change their own job titles are doing. You see, there’s this eternal murmur among tech writers, a chronic, low-grade grumbling, about how engineers get all the lauds and we get none, even though our work is just as important as theirs.

I agree: Engineers get the credit; we don’t. But to convolute our job titles in an attempt to match theirs (that’s what the “engineer” in “information engineer” is for) is to turn that insidious murmur into a roar. And that only earns us pity.

Besides, as tech writers our jobs are to take something complex and make it simple, easy to understand. We translate “tech-ese” into plain English. Whether our audience is a newbie end user or a rocket scientist, we are hired to explain, and to simplify. Shouldn’t we keep our job titles simple too?

There’s no question information is a commodity, a valuable one. And we tech writers are the brokers of that commodity. And there’s no doubt some people in IT do not appreciate our contributions. But I don’t think the remedy to that problem is to change our names. Perhaps a better approach is to do good work (without grumbling), attend project meetings (without jeering the engineers), and to point out ways to improve the product if we find them (without labeling the engineers “UI challenged”).

This way, even if we don’t get the credit we deserve, at least we have our self-respect.

Staying Off the Page

Karen Field CarrollUncategorizedLeave a Comment

I listen to NPR…sometimes against my better judgment, sometimes because of it. But I’m glad I listen, because NPR has taught me something important about technical writing.

NPR uses a variety of correspondents, not all of them silver-tongued. One man sounds like he’s gargling marbles as he delivers the news. Another correspondent has a lisp. (So do I, actually.) I like that NPR uses professionals who speak with the same impediments anyone could have. But there’s a limit.

One syndicated radio host in particular comes to mind. She has fascinating guests, experts who talk about politics, and art, and science. This woman queries her guests so well that they offer the most thoughtful answers you can imagine.

Or so I’m told. You see, our NPR friend has something called spasmodic dysphonia, a disorder in which one or more of the muscles of the larynx contract involuntarily. Spasmodic dysphonia makes a speaker’s voice halting, measured, stumbling. Our afflicted radio host speaks in a way that is both irregular and plodding. Her words fall from her mouth like bricks. The rhythm of her voice sounds like

Long story short, I’m so distracted by how this woman says something that I never really hear what she says. In this case, the messenger has become the message.

Technical writers become the message ourselves sometimes. Not in speaking, but in writing. When we’re writing procedures or describing a new piece of equipment, we forget that we have a message to deliver, and we get caught up in using fancy words to deliver it.

Consider these sentences:

  • If you wish to open the document, please click the File menu.
  • To open the document, click the File menu.

Which sentence sounds more natural? Which sentence sounds like an English butler with gender-identity issues? Which sentence would you use to explain something to your boss?

Because we’re writing in the business environment, I think a lot of us strive to sound formal (which in some cases means British). We use words like “ensure” and “facilitate” and “incentivize”—words that call attention to our writing style, and thus to us, because no one talks like that in everyday speech.

But good technical writing keeps the writer off the page, and it helps the user focus on the content. Good tech writing sounds natural, but not colloquial; it’s informal, but not disrespectful.

Staying off the page in technical writing takes practice, especially since the vocabulary we hear at work every day drips with technical jargon. But we can override the urge to sound like our techie counterparts as we write by asking ourselves, “Is this how I would describe something to a teacher or a boss?” If the answer is yes, we know that the user can focus on the message, not the messenger.


Karen Field CarrollUncategorizedLeave a Comment

I love lists. Numbered or bulleted, lists lay out ideas in a readable, digestible format. Lists corral unruly thoughts into a parade of hopes, goals, steps, or plans.

Lists rock.

As a techincal writer, I spend my days grouping data into lists–numbered lists for procedures, bulleted ones for general or nonsequential items. If I know anything about tech writing, it’s that a tech writer who doesn’t understand the gravity, the flexibility, the utter imperative of lists in good technical writing, a writer who hasn’t beaten bullet points into submission, is no technical writer at all.

Given the way lists govern my workday, it’s no surprise I’ve adapted them to my personal life, too. With 2010 coming up fast, I just created a tab in my planner (yes, I still use the paper version) called “2010 Goals.” Inside are two lists: one with goals for my job, the other, for my home life. My work goals are not really mine; they’re the things I know my boss wants me to get done. I love my job, so they won’t be onerous.

But my personal goals…ah, that list is a special thing.

I just learned to cook, at the tender age of–well, no longer twenty-something. So one goal involves experimenting with food. Good food. Not the “fat free” crap I’ve been patronizing ever since I discovered I had hips at age 13.

Another goal: Plant a garden. A vegetable garden. I’ll use the goods to help me meet the foodie goal.

A third goal: Organize the family pics, digital and otherwise. I’ll use categories: Richard’s family, my family, Richard and I together. Then I’ll subdivide: Kids, pets, holidays, fireplaces. (The last one is weirdly necessary. When my family poses for pics, we automatically look for a fireplace to stand in front of. Something about brick and flame draws us over, I guess. I’ll frame these and hang them–wait for it–above our fireplace.)

And my last goal? Start a blog about technical writing.