The Seven Deadly Sins of Technical Communication

Photo by Elena Leya on Unsplash

Written communication can fail in oh so many ways. The worst of these ways result from what I call the seven deadly sins. Avoiding them reduces this risk, though there are enough other sins (not to mention the sins of others) that there’s no guarantee. Still, avoiding these sins greatly reduces the risk you’ll fail to communicate.

Verbosity

Make the manuscript as short as possible—but no shorter. Avoid too-short, telegraphic sentences and don’t eliminate helper words like “the” and “that”. Sometimes you need a few extra words to give readers time to absorb what you’re saying. Complex concepts are particularly challenging, as they’ll always require more words than simple concepts. Even so, it’s usually possible to trim the fat without sacrificing the meat.

Assumptions

Before you start to write, ask yourself what readers must know to understand what you’re describing. Better still, ask your readers. Then provide that contextual information first. For example, Word 2019 for the Mac has 10 menus (each with up to 28 menu items) and 9 tabs in the Ribbon (each with up to 40 items per tab). Never assume that readers know where a tool is located amidst this cornucopia of features. Never ask them to look up that location. Sure, you could hope they’ll be willing to search the online help or Google to find a feature, but why not save them that time by explaining what they need to know?

Demanding too much

Don’t pack too much information into a single sentence or too many concepts into a single paragraph. The general advice that we should include one overall concept per paragraph and one supporting topic per sentence isn’t set in stone, but it’s a good starting point because it works. Even if readers are highly skilled—and many aren’t—why make them work unnecessarily hard? Also, avoid overloading readers with acronyms and abbreviations. This is particularly problematic in technical documents, where it’s sometimes difficult to see the text hidden amidst a thicket of three-letter acronyms (TLAs).

Failing to be inclusive

Sexist language offends and excludes readers. Gender-neutral language is easy to learn and quickly becomes second nature. For example, using imperative statements and the second-person “you” eliminates many problems in product documentation, and where descriptions are necessary, using the plural solves many problems: compare “readers should pay attention to these warnings, lest they suffer an awful fate” with “you should pay… lest you suffer…” The University of North Carolina’s guidelines are worth a look (https://writingcenter.unc.edu/tips-and-tools/gender-inclusive-language/), as is the Transgender Language Primer (https://www.translanguageprimer.com).

On a related note, our audience is increasingly international, so we must ensure that our information does more than meet the needs of English readers. Translate where you can; use clear and consistent language where you can’t. Use phrasal verbs with caution, avoid cultural references, and aim for simple, straightforward explanations. Spend more time sweating over the details than you would if you’re writing for an audience in your own country.

Inappropriate or careless reuse

Single-sourcing is great, when it works. Surprisingly often, it doesn’t, or at least glitches. If you reuse text and graphics, have you checked each reuse to ensure that it works perfectly in each new context? This can be tricky in the early days of learning this approach, when you’re still learning how to write for reuse. But even if you’ve mastered this skill, it’s easy to err by specifying the wrong chunk of information to be pulled from a text library or database. (You’d be surprised how easy it is to select the wrong item from a menu. Or maybe you wouldn’t.) This is particularly true if the nomenclature used to identify and retrieve information wasn’t well designed. Someone must always review the final product to ensure that everything that you reused works well in its new context.

Failing to test your instructions

Interfaces and features change during development. Have you tested the descriptions that you wrote weeks or months ago to ensure they’re still valid? This works best if, when you test, you do what the instructions actually say—not what you think they say, what you intended them to say, or what you already know they should say. If Dante lived today, he’d undoubtedly add a special circle of Hell for engineers who don’t use their own products and technical communicators who don’t use their own instructions before releasing them on an unsuspecting world.

Privileging your esthetic goals over reader needs

Sure, it sometimes becomes boring typing bland descriptions of product features, not to mention staring at the same highly readable fonts every time. That doesn’t mean you should embrace your inner artist and create works of art that please you, but that are unusable to your readers. (I’ve stopped counting how many times I’ve returned a book to the shelf rather than buying it because the typography made my eyes bleed.) If you want to be creative, start a blog and punish its readers with your… um… idiosyncratic choices. But when you’re practicing technical communication, stick with simple, clear, proven design choices.

Go forth and sin no more!

Unlike other deadly sins, these ones are more likely to land your audience than you in hell. These days, people have enough to worry about without us giving them something else to deal with. Strive to do better!


Zelda

11 months ago

Neither of the gender-inclusive language links works.

Ram P. Mony

11 months ago

On failing to be inclusive, why use such academic language? Why not write, “If readers heed these warnings, they can avoid …”

Geoff Hart

Geoff Hart

11 months ago

Ram, re. inclusive language: My specific word choice was to support the use of “you” (speaking directly to the reader). Nothing wrong at all with your suggestion, and pluralizing the subject (readers) is another generally good strategy for inclusive language.

Subscribe to TechWhirl via Email