Steven Jong

The Boston Globe today reviews N. M. Gwynne’s Gwynne’s Grammar: The Ultimate Introduction to Grammar and the Writing of Good English (available for pre-order on Amazon.com). Gwynne is a strict traditionalist and prescriptivist—in other words, a “scold”—who holds to the view that it’s been all downhill for English since Shakespeare.

I’ve been trying to improve myself with courses from The Teaching Company (highly recommended, by the way!), including some of their English language courses, and I know more today than they taught me in school. As a technical communicator, in the past I would have sided with Gwynne and other guardians of strict rules. No split infinitives! No jargon! Today I see myself more as a gatekeeper. I cannot, and should not, try to stop change in English, which is, for better or for worse, inevitable. But I can control the kinds of changes made, at least in the documents I’m responsible for—er, for which I’m responsible.

There have always been guardians of language who wanted to stop the wheel of change right where they stood. The French Academy actually has advisory authority on what is French and what is not. (They seem most concerned with keeping English words out.) But English has no such body, and anyway the language has changed continuously, and vibrantly, throughout its history. All spoken languages do.

It’s almost amusing to watch reactionaries trying to pick a moment when to hit the brakes. Why stop at Shakespeare? He personally coined upwards of 2,000 words, so it might have made more sense to stop just before him! And the wheel continued to turn after him; today, the Bard’s plays require heavy annotation to be understood. (There are passages that, if understood in their original sense, would be censored from every high school English textbook in the country.)

The Globe cites Jonathan Swift’s 1712 disparagement of—or may I call it slagging?—word constructions such as “disturb’d” for “disturbed.” I once edited a scholarly work on Milton, and in my ignorance I wondered why Milton used apostrophes that way. Surely there’s no typographic savings? But Milton wasn’t saving space, he was specifying pronunciations that fit his rhythmic meters, and also capturing the way people in his time were beginning to pronounce such words. “Disturbed” is spelled exactly as it was pronounced when English spelling was first typeset: a three-syllable word, “dis-TUR-bed.” But by Milton’s time the apostrophe captured a change in pronunciation, in this case to the two syllables we pronounce today: “dis-TURBD.”

In fact, the notoriously difficult spelling of English words, which foreign and native speakers alike despair of learning and Mark Twain mocked, is actually exactly correct and phonetically accurate, if you go back to when English spelling was regularized. The apostrophe convention in “disturb’d” eventually fell away, leaving the “regular” and understood pronunciation but an illogical spelling. Another example is “knight,” with half the letters silent, which is spelled exactly as pronounced at the time. (Combine the Danish name Knüt and the German word for night, nacht, and you’ve got it.) Maybe we should have stopped right then? We could still use the thorn (þ), an obsolete character from Old English pronounced “th” but initially printed as “y,” which is where we get the cutesy construction “ye,” as in “Ye Olde Twee Shoppe,” so annoyingly popular around these parts. But not even printing, which froze the written language, could stop the wheel.

I cut my professional teeth on Strunk and White. Modern linguists think of Strunk as somewhat fusty, but I’m a writer, not a grammarian, and I look to The Elements of Style for advice on writing well, not just grammatically. But I have learned that some of the rules aren’t actually rules. When scholars began to capture the rules of English grammar, the language already had Celtic, German, Norse, French, and Latin influences. The first English grammarians, following the model of Latin grammarians, presumed that English was descended from Latin and thus had to have Latin grammatical rules. But English is not Latin, and Latin grammar does not apply. Caesar could not have told his legions to boldly go where no man has gone before because the split infinitive did not exist in Latin. But Captain Kirk’s orders were correct.

What is the tie-in to technical communication? For one thing, we are deluged with jargon. It grows like weeds from several roots, including genuinely new ideas and usages, laziness, and ESL writers. I’m all for holding the line, especially when I can correct an error or use an existing English word. But some amount of growth and change is inevitable and not altogether unhealthy.

For example, I worked at a company that created products and services that caught people trying to defraud cell-phone carriers. Our marketing presentations called such people “fraudsters,” but I refused to use a made-up word, instead using the existing English word “fraud,” which means exactly what we intended and dates back at least to the 14th century. But the product manager insisted on “fraudster,” claiming we wanted to capture mindshare (yes, I know), and overruled me. I lost that one, but hey, I tried to stop the wheel. (Today a Google search reveals 1,250,000 Web instances of “fraudster.” I could claim our company made its mark on the language, but no; Merriam-Webster lists that word as well, and claims usage back to 1960.) Recently, though, I successfully held the line against “numberical” (yes, spell checker, I know) in place of “numerical,” even if it is a correct term in some small circles. And just this week I filed a bug against the use of “VSA`s” (back apostrophe and all) instead of “VSAs” in a label. We’ll see if I win that one.

As technical communicators, even if we let through some jargon, we still need to regularize spelling, grammar, and usage, even of jargon, for the sake of our readers. Even if the word is new, we can at least use the word in a regular way that lets readers decipher whether it’s a noun, verb, or adjective. For example, it’s too late to stop the verbification of “Google” (13.8 million hits today, and already in Merriam-Webster). Shakespeare would have verbified “Google.” However, if ever I am forced (kicking and screaming, I assure you) to use the verb “to google” in a technical document, I can hold the line against “Googling,” which is abuse of trademark, and ensure that the verb is used with correct English forms and tenses:

• I google, I googled, I will google …
• You google, you googled, you will google …
• He googles, she googled, he will google …
• They google, they googled, they will google …

(Interesting language trivia: Did you know that all irregular English verbs are old? No new verbs in English will ever be irregular. Why? See above.)

Oh, well: I’ll keep up the fight, but there’s only so much we can, or ought to, do. I intend to buy a copy of Gwynne’s book, and chortle over his astringent disparagements of modern English usage. If he doesn’t rail against “google” as a verb, I shall be disappointed.

There’s an old expression that to assume makes an ass out of u and me. (The phrasing works even better in the text era). I admit that many of my mistakes come from not checking my own assumptions. Is that what they really want? Is he postponing this week’s meeting, or next week’s? So my experience teaches me to question assumptions.

But it occurs to me that the expression is useful the other way, too. Turn the expression around and you get “assume questions.” Does this mean anything? I think it does, at least for technical communicators and instructional designers. In particular, I can think of three areas where this is useful:

• Preparing formal arguments and counterarguments
• Preparing for debate or legal proceedings
• Anticipating questions and objections and preparing in advance to deal with them

Concentrating on technical communication activities, the most obvious place to assume questions is in the frequently asked questions document, or FAQ. Now, I’m not a big fan of the FAQ. It should be assembled organically from sources of questions, such as customer support or training, but too often it’s used instead as a vehicle for “questions we want to be asked and answered” rather than questions users actually frequently ask. Often the FAQ format is an excuse for not organizing material. But done well, a FAQ answers genuine questions and addresses known points of confusion

(By the way, it should be the goal of the development organization to design away FAQs, through either improved design and error correction, or improved documentation that addresses such questions in advance.)

Another place to assume questions is in procedures. It’s common enough to document a straightforward march through a procedure—select this, enter that, click here, click there, and you’re done—and frankly, a travelogue isn’t particularly valuable. But what happens if there’s an error? How does the user know where to start and what the end point is? When they click OK, what happens? Nothing? A spinning icon? Five minutes of chugging away? That sort of information is truly valuable.

The easiest way to get into a user’s mindset is to try the procedure for yourself. Follow your own procedures and you’ll immediately catch some of the pitfalls. I admit I don’t do this enough in my own writing, but when I buy a consumer-electronics product), I can feel myself dropping into user mode, and my own questions leap out at me. If you’re too close to the product to get into user mode, the next-best thing is to apply the journalist’s six golden questions: who? what? when? where? why? how? They work for us too. In the classical IBM methodology, procedures must say who, when, where, and how to perform a procedure, using starting points, steps, and end points. That leaves “what” (what do users need to know to do the procedure?) and “why” (why do they need, or want, to do the procedure?). Those are, of course, prerequisites and conceptual background. The questions you can anticipate and answer represent a source of tips.

Where and how might users fail? If you have access to a support group, this is something they can tell you. Troubleshooting information can greatly strengthen and improve the usefulness of procedures, not to mention potentially reducing support call volume (so unless they’re a profit center, the support group should be happy to work with you). What do I enter here (not just “50 alphanumeric characters” but a concrete example)? What are my choices (not just how do I make a choice)? Why would I pick one choice over another (choose A for the highest throughput, or B if there are many local Wi-Fi signals)?

Let me give you an example from my subject domain. Imagine you’re writing a procedure to use a management tool to select subscriber records from the subscriber database. Why would someone want to do this? Because the subscriber session might not have been removed, or the subscriber might be calling with a problem. Okay, how do you do it? There’s a browser-based GUI page, and on it there’s an option to display all subscribers or search for a subscriber by phone number, which is how the subscriber database is indexed. Why would you want to search instead of just listing every subscriber? Because in the real world there may be millions of subscribers, and just listing them would overwhelm the system. (So it might be a good idea to document the search path first.) What’s the next step? The user is retrieving the subscriber record for some purpose; what are the operations that can be performed on the record? Finally, what sort of example would be useful? Perhaps a display of a retrieved subscriber record showing a problem of the sort actually encountered in the field. That’s useful information, whereas showing the search page with a fake phone number entered in the search field isn’t (that’s how to use the interface, not the function).

So, as I said, I endorse the idea of questioning assumptions, and I also suggest that you try to assume questions. It might make an ass out of you and me, but maybe not!

I got a soundbar for my birthday, to complement our big plasma TV’s little speakers. I did my Web research on soundbars, but couldn’t decide among all the types available, so I went to an electronics store and put my fate in the hands of a salesman. He sold me a brand I hadn’t been considering, but the price was right and it sounded fine.

When he explained how to program the soundbar to work with our remote control, he casually mentioned that there was a trick to it. “I didn’t understand how to do it at first,” he said. I listened, but in the back of my mind I knew I going to read the manual, so I was confident. There were only five buttons on the unit—how hard could it be to program? I should have picked up on the “trick” as a red flag.

When I got home, I took out the impressive-looking setup instructions (50 pages, in five languages) and followed them carefully, but failed to program the soundbar. Every sound-controlling button I pushed on my remote control just increased the volume. I even swallowed my pride and asked one of my sons for help. He rolled his eyes, picked up the manual, and spent half an hour on it before finally admitting he couldn’t get it to work either. (I ain’t quite as dumb as I seem…)

I belatedly turned to the Web for help. Reviews of that product were mixed at best. The consensus was that the sound was great but people couldn’t program it. On Amazon.com and other sites, a few people offered suggestions along the lines of the salesman’s “trick,” but most simply gave the product one star and warned not to buy it. (Remember, a one-star review on Amazon.com is really a zero-star review, because you can’t award less than one.)

Eventually I got to the root of the problem: there was a step missing in the instructions! The company’s own site has an FAQ that addresses the issue. Armed with a printout of the FAQ, I was finally able to get the soundbar to behave, and I’m going to keep it.

I wonder: How long has this been going on? Five years ago, Accenture, the technology consulting firm, pegged the consumer-electronics return rate at five percent, but discovered that only five percent of those returned products were actually defective. Of the rest, one in four is buyer’s remorse. However, more than two times out of three, the product was working correctly, but the consumer didn’t realize it. Some of that was due to mismatched expectations, but mostly the consumer thought it wasn’t working right even when it was. And this is a failure of the instructions (and sometimes product design).

Now, product returns are damaging on several levels. The costs of processing, restocking, repairing, and repackaging consumer-electronics returns was nearly $14 billion in the US even then. Beyond that, the reach of social media means that a bad product review reaches far more than the 22 people Dr. Deming once said a dissatisfied customer talks to.

So what? As I said, I found the fix on the Web. Why bother documenting at all when someone else will do it for us? Well, if you expect the wisdom of the crowd to fix your mistakes, you’d be taking a big chance. They may fix it while blasting your product and hurting sales. And if you’re like me, documenting a commercial product with only a few users, there is likely no one at all bothering to post corrections to the Web. More likely they’re suffering in silence, complaining to your support line, or recommending switching vendors.

Instead, I recommend rededicating ourselves to what we always try to do: a good job. Put yourself in your user’s place and make your procedures clear, complete, and correct. Use steps appropriate to your audience level, but don’t leave any out. Verify and double check. Best of all, include troubleshooting tips (as I suggest in my blog post “Back to Square One“).

I have one more suggestion. Companies need to know the value of technical communication, consumers need good instructions, and we need jobs. Today’s companies seek our approval by asking us to like them on Facebook. Well, what better way to help than to like them and, if necessary, call their attention to poor documentation? Who knows—you might trigger a fix, or even get a job writing their documentation! I call that a win all around.

Actually, I still can’t get the mute button to work. But I have a workaround.

It’s funny how the business cycle works. I’ve been working in the same office for five years, but thanks to acquisitions I’ve had four employers in that time, with the most recent change August 1. (Believe me, I’m not complaining!) For the purpose of this discussion it doesn’t matter what company it is; given its size and logo, let’s call it Big Red.

As technical writers, our value proposition is making the complex clear and explaining technical things to people. We aren’t subject-matter experts, but we know how to collect enough information, and present it effectively to let our audience use the technology to accomplish their goals. Rule One of user-interface design is to know the user, for the user is not you. It’s a key skill for us too: putting ourselves in the audience’s place and understanding what they already know, what they need to know, and how they approach the task.

Having more or less mastered the tools, technology, policies, and procedures of my previous employer, let me tell you that it’s a big shock going to the equivalents used at Big Red! To paraphrase Steve Martin, it’s like they have a different word for everything. All of us are back to square one, reset at a stroke from experts to new users. And we’re the worst kind of new users: we know how to do things, but not in the same way. Some of the most accomplished among us are now floundering the worst. I’m finding it a humbling experience, but valuable, too, because it’s a refresher course in how a new user feels, thinks, and approaches tasks.

What’s it like being a new user at Big Red? Because the company is so large and brings in so many people at once through hiring, mergers, and acquisitions, individual handholding is impractical; we are expected to rely on the technical and procedural documentation. (Hey, this is what we expect our audience to do.) And the environment is stressful, not through malice but simply because accomplishing certain tasks is now a job requirement or directly affects our lives. If I don’t complete this task I will lose my job; if I can’t accomplish that task I can’t log in; if I don’t do the other task my family will lose healthcare coverage. Mind you, it’s not as if we’re left without instructions. There’s actually plenty of information available. But it’s overwhelming. Today I followed a procedure that told me how to complete a procedure! A company with 1000 employees can grow a website with 25 links on the home page of its intranet, but a company with 100,000 employees can grow a website with 100. They can’t all stand out. Where is the one I need?

To make matters worse, in some cases, due to the sheer size of Big Red, I observe that Organization A refers to something on the Organization B website that has changed. We say we know the value of consistency and accuracy, but we sometimes get lazy about QA and don’t verify everything. When we’re writing and we spot a small inconsistency, it’s easy to convince ourselves that it doesn’t matter, because it’s obvious what to do. But in our current situation, we’re in no mood to be adventurous. If a procedure says to click the link that says X Y Z link, but all I can find is a link that says X Y Q, I’m not sure whether it’s the correct link or even if I’m on the right page. Have I really installed the XYZ collaboration suite if the desktop icon says XYZW? And if email directions specify a link that’s not there at all, which one is the closest match? I’m being forcibly reminded that when the stakes are high, tolerance for error and ambiguity is low.

As I said, we aren’t lacking for written procedures. Those procedures often contain plentiful step-by-step screenshots. Now, some on the creation side argue that screenshots are unnecessary because the user is already on the screen. And screenshots can be a pain to include. But such arguments miss the point. Screenshots can be vital user aids to consumers. These days I’m not sure where I’m going, and I’m finding anew that “you are here” screenshots reassure you that you’re on track.

When you start a procedure, how long will it take? Is it supposed to be that slow, or has the process hung? Engineering and product management hate to commit to performance figures, but it’s helpful to know, for example, that processing an email folder will take about twenty minutes per gigabyte.

And how do you recover if you do get off track? As technical communicators, we can easily fall into the bad habit of only taking our audience along the success path without considering troubleshooting. Let me tell you, even the simplest troubleshooting information can be as valuable as the procedure itself! Another useful aid is a “do not” admonishment, such as “do not click [similar-sounding link]; that is a different function.” Describing how to recognize and correct the top two or three possible errors in a procedure, even things you regard as obvious mistakes, will make the procedure more effective and increase customer satisfaction enormously.

Even something as simple as giving the end state of a procedure can be both helpful and reassuring. When I signed us up for healthcare benefits, I painstakingly followed the directions, but nothing happened. There was no message saying I was all set, no email confirmation of enrollment, and no medical cards in the postal mail. Our prescriptions began to run out. I worried that I’d missed some vital step. After a week I both emailed and telephoned the benefits office. That triggered one reply for each inquiry, and it turns out I had completed the procedure correctly. I can breathe easier (literally). But one extra statement in the procedure would have saved me misplaced anxiety and the benefits office two customer interactions. Multiply that by the number of new employees who have the same concern I did, and that extra statement seems like even more of a good idea!

So, what’s my closing statement? Know the user, for the user is not you. Don’t get jaded and assume everything is obvious. Don’t assume your audience is expert or won’t make mistakes. Attend to the details. Don’t ignore the value of screenshots. Include prerequisites at the beginning, troubleshooting tips in the middle, and closure at the end. Your readers will more often be successful, and grateful too!

[Updated 2/28/13]