Ambiguous Antecedent

Karen Field CarrollUncategorizedLeave a Comment

Being a technical writer and editor, I’m somewhat fond of style guides. The other day I found a good deal on the Associated Press Stylebook and Briefing on Media Law 2013, so I bought it and took it home. Flipping through the book later, I read this in the Foreword:

“The first Associated Press Stylebook was 60 pages, bound together with staples. It marks its 60th year as a comprehensive reference manual that fills more than 500 pages and is published across an array of digital platforms, encompassing the collective wisdom of its readers….”

There’s a subtle yet serious problem with the first pronoun and its antecedent. Before I explain it, here’s a refresher from 7th-grade English class.

Pronouns take the place of nouns. For example, in the sentence “She is so tall,” the pronoun “she” replaces the name of the person the speaker refers to. Pronouns save us work and make our speech more elegant. Without them, we’d have to repeat the name of the noun itself in every sentence we spoke about it.

Consider this sentence. “Karen just got here. You know, she is so tall. I wonder where she shops for dresses?” Without pronouns, we’d have to say “Karen just got here. You know, Karen is so tall. I wonder where Karen shops for dresses?” That’s ugly.

Sometimes a noun appears before its pronoun. In that case, the noun is called the pronoun’s antecedent. In the example in the previous paragraph, “Karen” is the antecedent of the pronoun “she.” And in the paragraph I cited from the AP Stylebook, “the first Associated Press Stylebook” is the antecedent of the pronoun “it.” So what’s the problem?

If you substitute the antecedent for “it,” you’ll see where the paragraph falls apart.

“The first Associated Press Stylebook was 60 pages, bound together with staples. The first Associated Press Stylebook marks its 60th year as a comprehensive reference manual that fills more than 500 pages…”

Even though the author probably meant to say that the current version of the stylebook marks the 60th year as a comprehensive reference manual, what he said was that the first version marks the 60th year.

Here’s a clear rewrite.

“The first Associated Press Stylebook was 60 pages, bound together with staples. The version you’re reading now marks the Stylebook’s 60th year as a comprehensive reference manual that fills more than 500 pages…”

I replaced the pronoun with the noun phrase “the version you’re reading now.” But I also changed the verb phrase “marks its 60th year” to “marks the Stylebook’s 60th year.” Why did I have to do that? The topic of the paragraph is the Stylebook, but the sentences talk about three instances of it: The first version (60 pages and bound with staples), the current version, and the stylebook as a living document. To be completely clear, I had to insert “the Stylebook” before “60th year” to reference its enduring state.

Am I being nit-picky? Maybe. After all, readers might figure out what the author meant. But they also might pause over the discrepancy—just because something “sounds wrong.” And if prose makes a reader pause, that prose is not plain language.






About the Samples in this Blog

Karen Field CarrollUncategorizedLeave a Comment

Sometimes the best way to teach a new way of doing something is to show an old way and describe the differences. I use samples from technical manuals, marketing materials, user guides, and other forms of business communication to illustrate some of the problems in professional writing, and to describe how to apply plain language to solve those problems. I violate no copyright laws in using these samples, and I never identify the text’s author or the product’s name. I do not use these samples to call out writers for their shortcomings in plain-language usage; I am in no position to point fingers, as I still find said shortcomings in my own work occasionally (and I use these samples in this blog too).

My point is, I use the samples I do because they help me explain the principle I want to explore in that particular post. Technical writers are busy, overworked, and often influenced unduly by members of a product-development team: In many cases, work that falls short of the plain-language gold standard reflects these outside stressors, not the writer’s talent or devotion to her work.

Stand in the Gap: Translating Product Feature Names into User Tasks

Karen Field CarrollUncategorizedLeave a Comment

I haven’t always known about plain language. Before I began studying it, I wrote as clearly and concisely as I could, but I missed an important principle: Translating product features into user tasks. Here’s what I mean:

The other day, when editing a help file, I came across a topic I’d titled, “Using Pay Invoices Online.” Clear enough, yes? Sort of. Because the feature is aptly described, users can figure out that, using this feature, they can pay their invoices online. But what if I titled the topic, “Paying Invoices Online”? Users could then omit the mental step of figuring out if that feature will help them complete their task.

With a well-named feature like this one, applying the task name to the topic closes a small gap between user and product. But with a poorly named feature, it can close a chasm between them.

The Language Link

Karen Field CarrollUncategorizedLeave a Comment

I’ve worked in technical communication for almost two decades. I’ve written user guides, online help, newsletters, tutorials, reference guides, API specifications, and user interface text. I’ve written the documentation for tax software, task-management software, science-lab hardware, and system-to-system technology used by the mortgage industry. I’ve even written humor columns and articles about technical communication.

My favorite aspect of technical communication is its diversity. To produce useful documentation, we as technical writers must know our products and their underlying technology, our users’ goals, our users’ industry, our tools, and our subject matter experts’ temperaments. We have to know our way through a project, and we have to know our way around a sentence.

Let me say that again: We have to know our way around a sentence.

Consider your last project. Whether it was an online help system for flight-tracking software or a fact sheet for a webinar on aging, you probably did several things. You gathered the specifications for the project, talked to its developers, wrote user stories to reflect the project’s requirements, used the product yourself, decided which desk-top publishing tool would produce the right type of document, designed the appearance of the documentation, and outlined the content. And then, you sat down to write.

Now consider the project from the user’s point of view. She probably heard or read about the software or webinar, launched the software or clicked a link, found her way to the information you wrote, and read it.

Think about that: You wrote; she read. All the planning you did, all the information you gathered, all the tools and technology you learned—in short, all the steps you took to package the information for the user—helped the user access the information. But it was the information itself she came looking for. And to understand that information, she needed language.

Language—the words writers use–links the writer to the reader. Language is what the writer employs to explain the product, and language is what the user needs to understand the product. Whatever else a help system uses to deliver a message to the user—images, video, web pages or printed ones–the message itself comes wrapped in language.

Technical writers know this; we know that our writing matters. Our language skills matter. So why are so many of us still such uncommitted writers?

Thinking about Writing: It’s Illogical

Karen Field CarrollUncategorizedLeave a Comment

Recently I picked up Robert Lane Greene’s book You Are What You Speak. I love reading books about language, especially ones that discuss the various dialects of English, and so I thought my romp through the pages of this one would be another such awe-inspiring tour of my native tongue.

I was wrong. From the first chapter, the author’s tone told me this was less a book about English speakers than a rant against English speakers who happen to be conservative. (I don’t mean people possessing conservative views of the language—what Greene calls “grammar grouches”—although he doesn’t seem to like them much either. Rather, conservative thinkers.) Fine, but not what I was hoping for. I trundled on; maybe the author would surprise me and change his tone.

He didn’t. In fact, he looped other writers into the morass. He went on to rail against Bill Bryson, who wrote The Mother Tongue, and Lynne Truss, author of the loved and lauded Eats, Shoots, and Leaves. Grrrr. Finally, on page 57, I had to abandon the book, because the author did something that made me stop trusting him altogether: He used faulty logic. Worse: He expected me not to notice.

Greene wrote that several prominent authors had published articles or blog posts on President Obama’s apparent affection for the word ‘I.’ Quoting a study from the language blog Language Log, he writes, “The word ‘I’ comprised 4.5 percent of the words George Bush used in his first two press conferences; Bill Clinton’s rate had been 3.9 percent. Of Obama’s words in his first press conference, just 2.9 percent were ‘I'” (p. 57).

If you read it carefully, you’ll spot the chasm in his argument.

To get you started, ask yourself these questions:

  • Does the author mean George Bush used the word “I” 4.5% of the time in toto (over both pressers), or in each one?
  • Same for Bill Clinton: Is that 3.9% total for both press conferences, or in each one?
  • Why does the author cite two press conferences for George Bush and Bill Clinton, but only one for Barack Obama?
  • Does that include use of first-person pronouns in other forms (my, me, mine, and so on)?
  • How many words did each president say in each press conference?
  • How many of those “I”s were self-promoting (“I am here to fundamentally transform America!”), how many were self-deprecating (“I’m deeply sorry for the pain my decisions have caused the American people”), and how many were neither (“I’m not sure. I’ll have to ask Jay Carney”)?

(To find some answers, I read the Language Log blog post that served as Greene’s source. It’s no less murky.)

I suspect I’d be on a fool’s errand to take this further, but I wanted to show you how writers often assume the logic in their writing smacks of authenticity, when in fact it reveals only an agenda.

Adversarial Adverbs

Karen Field CarrollUncategorizedLeave a Comment

Ah, the humble adverb. Writers use adverbs to emphasize a point, deepen a sentiment, refine an action. The problem is, adverbs do just the opposite.

Consider this sentence. “I am truly sorry.” The adverb “truly” qualifies “sorry.” The listener’s obvious question is, “As opposed to not being truly sorry?” Adverbs rob good words of their power.

Or how about, “I quickly ran to the store.” “Quickly” qualifies “run.” But “quick” is a property of the verb “run.” After all, you don’t run anywhere slowly. Adverbs often harbor redundancies.

My freshman English teacher taught me and my classmates something wonderful about adverbs: They can be made useless. In a vocabulary lesson, he asked us to list as many synonyms for the verb “walk” as we could think of. I came up with “stride,” “tiptoe,” “trot,” “saunter,” and so on. In a 10-minute exercise, Mr. Parker showed me that you can best describe an action by using a precise verb. Consider the verb “saunter.” Isn’t “She sauntered down the street” more vivid than “She walked slowly down the street”? And this wonderful word conveys the actor’s mood, too. After all, you saunter when you’re calm, confident, but not when you’re downtrodden or tired. Adverbs often make something specific into something vague or weak.

But in technical communication, they can do more damage than that: They can thwart the purpose of the document itself. How many times have you read a sentence like this: “Using our product, you can quickly and easily organize your computer files.” Or this: “Please click the File menu.” (Yes, “please” is an adverb here.)

In technical documents, which are by definition factual, adverbs reveal opinion, salesmanship, or writer sentiment. (For example, when a writer uses “please,” she’s trying to avoid sounding harsh to the user.) So the next time you catch yourself typing an adverb, ask yourself why. Are you telling the user what you think, trying to convince her of something, or tiptoeing around her feelings? Don’t.

Or maybe I should say, “Please don’t.”

Afterthought: I edited this post several times in an attempt to get rid of the adverbs I’d used outside of my example sentences. I couldn’t eradicate all of them. Adverbs are insidious word weeds.

Adopt the User’s Perspective

Karen Field CarrollUncategorized

Learn to see what your users see. Read my latest post on the STC’s blog “Notebook”:

A New Year, a New U(ser’s Guide)

Karen Field CarrollUncategorized

This is not a blog about writing. I feel compelled to say that because so many people hear “plain language” and think “text” or “words.” But I’ve studied plain language in technical communication for several years now, and so I know that using plain language in documentation begins long before we sit down at our keyboards to write. Instead, the journey to the clear, readable documentation the plain-language approach delivers to a product’s users begins the day we say, “How does my user see this product? What does the user need to know?”

In other words…

The day we say, “I am the user’s mentor, not the company’s mouthpiece,” we begin writing plain-language documentation.

The day we say, “I need to know what the user needs to know,” we begin writing plain-language documentation.

The day we say, “The tools I use to create documentation can help me work quickly and efficiently, but they are not what matters to the user,” we begin writing plain-language documentation.

The day we say, “I want to present the information in a way that does nothing to distract the user from the message,” we begin writing plain-language documentation.

The day we say, “I want to write text that sounds like a user, not a product developer, wrote it,” we begin writing plain-language documentation.

Finally, the day we say, “I want to use words and images that anyone from a rocket scientist to a high-school dropout can understand,” we begin writing plain-language documentation.

If you join me in this approach, you need to know something: It’s not as much fun as spending hours learning a new content-management system or writing html code for a Web page; It’s work.

But then again, it’s much more satisfying. You learn your products. You advocate for your users. You educate your coworkers about the user’s goals and her perspective. Then you discover that your coworkers–the business analysts, product managers, even the developers you work alongside each day—are starting to consult your documentation for the “plain English” explanation of a feature or a concept. You overhear people say things like, “Ask Karen to write that product summary. She can explain anything to anyone.”

At least, that’s what happened to me. If you read this blog and use its advice in your own work, it can happen to you too.