Crystal clarity

Avoiding Confusion: A commonsense approach

Check out this product description:

Work has been proceeding in order to bring perfection to the crudely conceived idea of a machine that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such a machine is the Turbo-Encabulator.

Did you get that? Yeah, we didn’t either.

The Turbo-Encabulator is completely made up. But, when a description of the Turbo-Encabulator ran as a joke in a 1946 edition of Time, most people thought it was real. Why? Because they’d seen so many other bad manuals and product descriptions like it before. The Turbo-Encabulator is a parody of technical writing and, as with all parodies, it’s funny because it’s based on reality.

This, on the other hand, is 100% bonafide:

The delay knob moves the main sweep horizontally, and it pauses at 0.00s, mimicking a mechanical detent. At the top of the graticule is a solid triangle symbol and an open triangle symbol. The symbol indicates the trigger point and it moves with the Delay time knob. The symbol indicates the time reference point and is also where the zoom-in/zoom-out is referenced.

Granted, this oscilloscope operator’s manual isn’t designed for a novice. But the writers unnecessarily mention a “mechanical detent” and a needless passive sentence “is referenced.” It just makes the sentence hard to understand.

So, how do you avoid confusing your reader? Keep in mind that real people will read your writing, and they probably aren’t as technically knowledgeable as you are. Here are a couple of suggestions to make your writing more humane:

Use Plain Language: Did you know that Plain Language is a movement? Plain language “is focused on readers.” It ensures that your readers can “quickly and easily find what they need, understand what they need, and act appropriately on that understanding.” Use plain English, words that most people understand, and short sentences.

Lay off the jargon: Or, at least, use it as sparingly as possible. Jargon is only used within a specific discipline. Chances are, no one outside of your industry knows what it means. If you absolutely need jargon, do your best to provide context, short definitions, or even a glossary of terms. Sometimes, jargon just makes you sound silly. Case in point:

Extra-Lift Carriage Control Lever
Brings small items close to the top of the toaster, for easy removal.

An Extra-Lift Carriage Control Lever? For easy toast removal, you say? Good for you… but the rest of us just call that a “lever.”

Don’t turn verbs into nouns: Verbs are happy being verbs. Don’t force them to become nouns when they don’t want to be nouns. Verby nouns makes your sentences unhappy, which in turn makes your readers unhappy.

Here are some completely unparsable work instructions for an automotive assembly line:

Now, we’re not sure what’s happening with the punctuation—and we’ll likely never sort it out. But the nounification of those verbs, we can rectify. Here’s how we did it:

Articles are not the enemy: Articles are those little words in front of nouns, like “the,” “an,” and “a.” When writing instructions, people have a tendency to skip articles altogether. They say things like, “Disconnect cord from wall” instead of “Disconnect the cord from the wall.” We have yet to suss out the reason for this omission, but we assume that it is rooted in a deep-seated desire to sound like a robot. Until the singularity strikes, feel free to use articles whenever they are called for.

Turn it over to a novice: Sometimes it can be hard to tell when your writing is unclear. Want to make sure? Give your writing to someone who knows nothing about the subject matter. Try a Hallway Usability Test: hand what you’re working on to five random people who just happen to walk down the hall. Every time someone says, “I don’t know what this means,” you’ve gone off the rails on the clarity train.

iFixit’s original field service manuals were tested on unsuspecting art students: we handed them a computer and our new manual and watched them use the instructions to take it apart. Every time they got confused, we knew we had a problem. We used what we learned from their attempts to make the service manual better.

Don’t use weasel words: Some words weasel into your sentence and steal your oomph. Words like “quite,” “mostly,” “slightly,” “seems,” “sort of,” “pretty,” and “somewhat” are built-in sentence loopholes. They signal to the reader that you mean what you say … just not really. Is the screw “pretty hard to tighten” or is it just hard to tighten? Is running into your ex “fairly uncomfortable” or is it just downright uncomfortable? Say what you mean without wishy-washy words.

Chapter 2

Chapter 4