Steven Jong

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]

As I write this, the anniversary of the publication of Herman Melville’s Moby-Dick (as it was originally titled) is noted on Google. The novel is getting a celebrity Web reading. What timing! I recently finished listening to a complete audio recording. (Thanks, LibriVox.org!) The work is on the short list of consensus nominees for The Great American Novel, and I recommend giving this challenging masterpiece a listen (or a read).

There are many fine analyses of the novel, to which I cannot add. Melville’s first two books were actually memoirs of his travels in the Pacific, but the settings and events were so fantastical that readers and critics alike took them for fiction. Moby-Dick was also inspired by true-life events: the 1820 sinking of the whaler Essex by a sperm whale, and a legendary white whale called Mocha-Dick that allegedly survived over 100 encounters with whalers. Melville did extensive research on the subject, and this time, even though he was writing fiction, he wanted to establish verisimilitude. He intermixed fact and fiction in 135 often confusing chapters, plus etymology and epilogue, throwing together first-person narration, omniscience, stage directions and labeled dialogue, free-standing short stories on various subjects, and long technical treatises complete with footnotes. In the non-fiction, technical chapters, he presents detailed information with precision and clarity. In those chapters I think I recognize the kindred spirit of a technical writer.

First, Melville was a masterful writer who constructed vivid, impeccable sentences. He had actually served on a whaler, so he had experience on which he could draw. (It always helps to understand your subject matter!) To supplement his personal experience, he plainly made extensive study of the techniques, science, history, and literature of whaling, and in various chapters he passed on what he had learned. (Learning and then teaching are subconscious joys of technical writers.) In the book he goes into great technical detail about the construction of whaling vessels and chase boats, the anthropology of the characters, the biology and comparative anatomy of whales, the psychopathology of monomania, the sociology of religion, and even what he understands of the whale’s relationship with other species (anticipating Darwin by eight years). In these chapters Melville writes with authority and clarity. Chapters 74 (“The Sperm Whale’s Head—Contrasted View”) and 75 (“The Right Whale’s Head—Contrasted View”) are intermezzos after these two whales were taken in the fictional narrative, but might as well be part of a text on comparative marine anatomy, where they would serve as vividly written walkthroughs.

Indeed, part of the difficulty of Moby-Dick is its digressions, which interrupt the narrative flow and annoy the reader who just wants to get on with the chase. (In his screenplay for the 1956 movie, Ray Bradbury, who confessed he could never get through the book himself, ignored all those chapters.) But it’s all right to skip them. In technical-writing parlance, those chapters are modular, and can be read in any order or skipped at your convenience. The fictional narrative was the organizing structure through which the technical chapters were interspersed.

Not everything Melville wrote was accurate, of course. He, or at least Ishmael, rejected prevailing theory and incorrectly regarded the whale as a fish, not a mammal. He also listed the blue whale as apocryphal. But most of what he wrote is correct and accurate, and serves as a record of the lost practices and technology of whaling.

By the way, Melville was like a technical writer in one other respect: the first edition of his book was incomplete and needed updating. The version that appeared in England was rushed to press and lacked the epilogue, which explained (spoiler alert!) that Ishmael, the narrator, survived the encounter with Moby Dick. (The initial critical reviews harshly questioned who could be telling the tale if all hands perished.) As any technical writer will tell you, always inspect the golden master!