|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 2021 --> Avoid the seven deadly sins of technical communication
Vous êtes ici : Essais --> 2021 --> Avoid the seven deadly sins of technical communication
By Geoffrey Hart
Previously published as: Hart, G. 2021. Avoid the seven deadly sins of technical communication. https://techwhirl.com/the-seven-deadly-sins-of-technical-communication/
There are many ways written communication can fail. 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.
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.
Before you start to write, ask yourself what readers must know to understand what you’re describing. Don’t assume you know. 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?
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).
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...” (Note that “they” has been used for centuries as a singular form, so it’s suitable in most place where specifying gender is irrelevant.) The University of North Carolina’s guidelines are worth a look, as is the Transgender Language Primer.
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 into the reader’s own language 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.
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 applying 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.
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.
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.
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—virtuously!
©2004–2024 Geoffrey Hart. All rights reserved.