Only You Can Make it Plain

Karen Field CarrollUncategorized

Last week I wrote an article for a charity newsletter about the charity’s annual banquet. I opened with this paragraph: We’d had a lovely evening. As I sat at our table at the banquet last month, check book open, pen poised to jot down a donation, I looked back over the last two hours.

(Yeah, not my best work. Let’s move on.)

When the charity’s director sent me the final piece, I noticed she’d replaced a comma with a semicolon: “….pen poised to jot down a donation; I looked back over the last two hours.”

I growled. Then I fumed. Who on earth, I thought, would have the gall to edit a professional writer’s article without consulting her first? My name is on that piece, and now it’s laughably wrong.

Taking three deep breaths, I wrote the director back and explained that the semicolon was incorrect. I told her that semicolons separate two complete, but closely related, sentences, and that the first part of the sentence in question was a dependent clause, not a complete sentence.

She wrote back and agreed to put the comma back in, adding, “But Word told me to use the semicolon.”

Ah. So it wasn’t gall; It was Word. Or maybe it was Word’s gall.

I can’t count the times I’ve used Word’s spelling- and grammar-checking “feature” only to discover that Word proposes erroneous—and sometimes ridiculous—changes.

I could spend a few hours researching the logic Word uses to verify spelling and grammar and then tell you how to work around it, but Word just isn’t worth my time. Instead, I’m going to tell you this: You don’t need Word to check your grammar. You’re the technical writer because you know how to write, not because you know how to use Word (or FrameMaker or MadCap or DITA-plus-the-content-management-system-du-jour). You understand spelling and punctuation. You know that semicolons are really just soft periods, and you know to use them sparingly in plain-language writing. You could spot a widowed transitional verb from four paragraphs away. You know the rules of English and when to break them. You know how to write.

Don’t you?

It’s not grammatical perfection I’m clinging to. (Notice how I ended a sentence with a preposition. English curriculums still teach school kids that that’s wrong, but you and I know standard English allows this syntax today.) But English, like all languages, has its rules. And everyone who speaks English knows them (to a greater or lesser extent; when I read some people’s Facebook posts, I realize I’ve encountered people from the “lesser” realm).

To illustrate, here’s a sentence I’ve never used before:

The blue, bear-like mountains seemed to lurch toward the green glaciers before them.

I can write—and you can read and understand—a sentence I’ve never used before because we know the rules of English syntax. What makes us writers, though, is not that we know the rules; It’s that we know how to use them well. We have command of them, you could say, and we use our mastery to write text that is clear and readable.

As for the article about the charity banquet, I overcame my indignation when the director told me she’d gotten that semicolon from Word. Then I gave her the same advice I’m giving you: Rely on your own experience as a long-time speaker of English, not some software’s spell-checker, to tell you when a sentence doesn’t make sense. If you’re not sure, look up the info you need online.

Apps like Word can check your writing for spelling and grammar errors (however misguided the results), but only you can make your writing plain.

One Word Turns Pain into Plain

Karen Field CarrollUncategorized

Recently, due to an almost-fire in the kitchen that filled the house with smoke but not with the shriek of our supposedly working smoke detectors, I decided to test said detectors. Online I discovered a product designed for just this task, a spray called Chekkit Smoke Detector Tester. The can tells me that when I spray Chekkit near a smoke detector, the detector should sound. In fact, here are the instructions:

  • Shake well before use.
  • Holding can upright, spray at detector from no closer than 12″ and no further than 40″.
  • Release only a 0.05 – 1 second burst of aerosol, repeating every 10 seconds as necessary.
  • If detector fails to respond, it may be faulty.

Clear enough, yes? Well, I see four problems with this procedure, but two of them affect the instructions’ clarity, so let’s focus on those.

The first problem appears in the second step. When I read the phrase, “spray at detector,” I paused, musing: There are eight detectors in my house. Do I test every one? Is there a primary detector that I should check? If one detector sounds, are they all okay?

I decided that the instructions implied I should test each detector. Adding one word in step 2 could have saved me this confusion: Each.

  • Holding can upright, spray at each detector from no closer than 12″…

And because I know that leaving transitive verbs without objects can fog up instructions, I’ve added “Chekkit” after “spray.”

  • Holding can upright, spray Chekkit at each detector from no closer than 12″…

(Yes, yes, Chekkit writer: You had little space on the back of the can for these instructions; I get it. But you could have downsized the logo at the bottom of the column to make room for these “extra” words. Fight the good fight.)

The second problem occurs in step 3. Here’s my question: What does “as necessary” mean? How many times do I squirt this fake smoke at an apathetic detector before I know the thing is broken? Three times? Ten times? Fifteen times?

I can’t rewrite this step because I don’t know the answer, so I’ve applied the “reasonable smoke detector” test to the problem. That is, I believe a reasonable working smoke detector should squawk after I give it no more than five squirts.

One word can answer a question before the user has to ask it. A phrase that uses concrete adjectives and nouns can prevent the user from making up her own rules about how the product might work. This is the difference plain language makes in technical communication.

(And what are the other two mistakes I noticed in the procedure? First, the writer needed numbers instead of bullets for steps–and the last step isn’t really a step;. It’s a feedback statement. Also, the writer used “further” when “farther” is the correct term. I didn’t break my pencil point over this one, though, because its meaning is clear enough. And using plain language isn’t about being a grammar ghoul; it’s about using the clearest terms possible and letting go of things that won’t perturb the reader, even if they are a bit off.)

 

 

 

The Style Guide Every Plain Language Technical Writer Needs

Karen Field CarrollUncategorized

Forget the Microsoft Manual of Style. Forget Sun Microsystem’s Read Me First! I recently came across John R. Kohl’s The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market, and it is now my only resource for questions of grammar, style, and clarity in plain-language writing.

Kohl wrote the book for “anyone who uses written English to communicate technical information to a global audience,” but his “global English” principles, which he developed to make the process of machine- or human-translation of documentation more efficient, echo many plain-language principles. Although I don’t agree with everything the author says in the book, I find so much of it valuable and interesting that I can confidently recommend it to you.

Be forewarned, though: In studying Kohl’s work, you’ll learn more about our language’s structure and rules than you even knew existed. And you won’t regret it for an instant.

Thinking about Writing: It’s Confused (and Opinionated)

Karen Field CarrollUncategorized

I spent an hour on hold with the phone company the other day. One of the advertisements I endured during my wait talked about the company’s high-speed Internet services. “You can download a standard-length song is as little as two seconds,” said the voice, “your favorite TV shows in as few as two minutes, and a full movie in as little as six.”

As little as…as few as…as little as…. These shifting modifiers serve no purpose. What were the writers thinking?

I’ve called this series of posts Thinking about Writing because when I started analyzing why text works or doesn’t work, I realized that most mistakes in writing result not from the writer’s lack of skill, but from the writer’s lack of thought.

In our example, look at the nouns that the words “little” and “few” modify: seconds and minutes. Both nouns are units of time, which means they’re countable nouns. Because “few” modifies countable nouns and “less” modifies uncountable ones, the best modifier here is “few.” Here’s my rewrite:

You can download a song in as few as two seconds, a full-length TV show in as few as two minutes, and a full-length movie in as few as six.

This is a blog about plain language in technical communication, so let’s take the sentence into user documentation. When we do, we find the sentence has another problem, one that isn’t a problem in a commercial but offends in technical communication: It’s opinionated.

People, including writers, often forget their own subjectivity. If you use the modifier “as few as” in this sentence you imply that (a) you think that’s really fast, and (b) the user should agree with you.

The user might, or she might not. It’s not the technical writer’s job to decide for the user whether something is fast. But you can still explain the idea clearly—without modifiers.

You can download a song in two seconds, a full-length TV show in two minutes, and a full-length movie in six minutes.

(I’ve added the final “minutes” to eliminate ambiguity.)

When it comes to describing a product’s functions, remember: Facts, not fascination.

Thinking about Writing: It’s Contextual

Karen Field CarrollUncategorized

A confession: When I’m not writing, reading, loving on my pets, hanging out with my husband, exercising, or stitching, I’m watching HGTV. So I guess it’s no surprise that I’ve learned something about plain language from the network: the importance of context.

The show: “Sarah’s House”
The speaker: Interior designer Tommy (who’s adorable, by the way)
The topic: The layout of a master bedroom under renovation
The problem: Tommy said, “We deleted a closet [so we would have more room].”

The word “deleted” in that context, the context of home remodeling, irked me. People don’t delete closets, I thought. They remove them, take them out.

I know what you’re thinking: The guy’s an interior designer, not a Rhodes Scholar; Quit being so judgmental.

And you’re right. Tommy committed no real sin. This is interior design, after all, not a user guide for dismantling the Hubble space station. But allow me to use my criticism of what the adorable, talented Tommy the interior designer said as a springboard to something important in professional writing: The relationship between context and word choice.

First, consider the realm that bled the word “delete” into our vocabularies: technology. That’s one context. Now consider HGTV’s programming: interior design shows, real estate shows like “Property Virgins” and “House Hunters,” the occasional “Whoa!” show like “You Live in What?”  That’s a different context. And judging from the line-up, people who watch HGTV are more interested in paint chips than computer chips.

Another example: If I’m writing a user guide for a spreadsheet application and want to explain how to remove a column, I wouldn’t say “To unload the column…” because it doesn’t make sense. And I wouldn’t say, “Get rid of the column…” because it’s too colloquial. I would say, “To delete the column…” because “delete” is a word users familiar with spreadsheets expect.

C’mon, you say. People knew what Tommy meant; that’s all that matters.

In this case, you’re right. But in professional writing, the words we use should be just as important to us as paint colors are to interior designers. When professional writers use a word out of context, it’s like a designer painting the living rooms walls of her introverted,  soft-spoken client chartreuse.

Ick.

Thinking about Writing: It’s Tense

Karen Field CarrollUncategorized

I love commercials; They give me so much fodder for my blog. Here’s a line from a recent commercial for a stop-smoking drug. In the ad, the speaker describes how she reacted when her doctor told her about the drug.

“When the doctor told me I could smoke the first week, I’m like, OK. Little did I know that, one week later, I wasn’t smoking.”

Does the statement sound strange? It should. Setting aside the distracting colloquialism–“I’m like, OK”–which has its own problems, the speaker makes a serious mistake in verb tense. Before we analyze it, however, let’s figure out what verb tense really is and why it matters.

My favorite definition of verb tense comes from the University of Ottawa: “A verb indicates the time of an action, event or condition by changing its form. Through the use of a sequence of tenses in a sentence or in a paragraph, it is possible to indicate the complex temporal relationship of actions, events, and conditions.”

In other words, verb tense explains the speaker’s place in time, as well as her view of actions or events in regards to the past, present, or future. In doing so, it orients the listener to the speaker’s frame of mind.

Here’s the offending statement again. 

“When the doctor told me I could smoke the first week, I’m like, OK. Little did I know that, one week later, I wasn’t smoking.”

The clause “When the doctor told me I could smoke the first week” uses the future unreal tense, which people use to talk about what might happen. It’s a look into the future. The dependent clause in the next sentence, “Little did I know…” appears to continue the future unreal tense. Little did I know, sitting there in the doctor’s office that day, when he told me I could smoke the first week I took the drug, that, looking into the future…. She’s still sitting in the doctor’s office–and so are her listeners–talking about things that haven’t happened yet.

So you see why “I wasn’t smoking”–the past-progressive tense, by the way–violates the speaker’s perspective on time. She’s abandoned her listeners in the doctor’s office and leapt forward, not only to the week she ends up not smoking, but beyond it–far enough beyond it, in fact, to look back over her shoulder and say, “Wow, I wasn’t smoking that week.”  The listener needs a time machine to follow the speaker’s thinking.

What’s the solution? The speaker should have said, “Little did I know that the following week, I wouldn’t be smoking.” This continues the future unreal verb tense. She’s still in the doctor’s office looking forward. I didn’t think it was possible, sitting in the doctor’s office that day, that I wouldn’t be smoking the following week.

For most English speakers, including me, 7th-grade English class was a long time ago. But because I speak and hear the language every day, I, like other English speakers, know almost instinctively how to construct sentences according the rules of the language. When I saw this commercial, I didn’t think, “The speaker is using the future unreal tense inappropriately!” But I did think, “That’s the wrong way to express that thought.”  I’m jarred and distracted when someone doesn’t follow the rules that most of us know by heart.

I don’t know why the commercial’s writers or producer didn’t hear the problems in the speaker’s statement. I suspect they overrode their judgment to let the speaker tell the story “in her own words.” If that’s the case, they lost their edge, and their audience, when the speaker opened her mouth.

Thinking about Writing: Mutilated Metaphors

Karen Field CarrollUncategorized

In this blog, I teach how to use plain language to write clear technical documents. To me, plain language equals good writing. To teach the principles of good writing, I like using examples of bad writing.

To do that, I need examples of bad writing, and they aren’t hard to find. Usually, I just have to turn on the TV and watch a few commercials.

Here’s one. In a commercial for Lear Capital, which sells gold and silver, the speaker says, “When the government prints money faster than a hungry cheetah, your dollars and paper investments can get eaten alive.”

I’m sure the writers thought the hungry-cheetah analogy complemented “eaten alive,” but it doesn’t. It actually attempts to quantify how fast governments print money. But it fails. Badly.

The speaker is using a metaphor.  Writers use metaphors to explain the traits of one thing by exploiting the traits of something else. Some metaphors that work: He’s a rock star (implied: a highly successful person), or  She’s deadweight (implied: a burden on everyone).

The implied meaning of the metaphor in the commercial is this: The government prints money faster than a hungry cheetah prints money. (I hope you’re scratching your noggin here.) Probably what the writer meant was “the government prints money faster than a hungry cheetah can run.” Neither scenario works. The problem with the first meaning is that cheetahs can’t print money. If they could, they’d probably buy their dinner instead of chase it. The problem with the second meaning is that it compares two disparate acts: printing money, which is measured in number of copies per period of time, and running, which is measured in miles or kilometers per hour.

What the writer wants to say is that the government is printing money very fast. To make the metaphor work, the writer needs to compare how fast the government prints money to how fast something else is printed. ( I can’t think of anything that prints something faster than government prints money, which probably explains, but does not excuse, the writer’s stretch for the hungry-cheetah phrase.)

If you’re a technical writer like me, you might be thinking, “I never use metaphors in my documents. Why is a blog about plain language in technical writing explaining metaphors to me?”

Excellent question, and here’s the answer: Because this exercise is less about using a writing device effectively than it is about thinking critically about what you hear, read, and ultimately write. You as a writer should notice when something sounds “off.” When you do, ask yourself some questions: What was the writer trying to say? Why did they fail? How could the writer improve the message? To write well, you have to analyze writing–yours and others.

Now, go watch some TV.  Consider it a writing assignment.