Chapter 4

Communicating with style

Manuals aren’t pulp fiction page turners. But that doesn’t mean they have to be a snooze-fest. Instructions are important. People need them. As writers, it’s our job to make reading manuals not feel like a chore. Write with style.

Style doesn’t necessarily equate to poetic language and intense imagery. Every writer, no matter how technical the material, has a style. Style is how you, as an author, choose to communicate with your audience. It includes things like tone, humor, and the degree of formality in your writing. Good style is about making decisions—about knowing what to include and what to omit, when to follow the rules and when to break them.

You can break all the rules that we’ve listed, but you should do so for a clear reason. For example, in Chapter 2 we told you to be direct and avoid tangents, but sometimes the best way to explain a feature is to include an anecdote. In that specific moment, it’s fine to break that rule. The benefit of storytelling outweighs the perks of being concise. Just don’t go around breaking rules without good reasons for doing so.

Mackie’s user guides are an inspiration. Mackie’s style is instantly recognizable. They know their audience—professional sound engineers—and how to reach them. They address their readers like friends, while still passing on detailed instructions and expert-level knowledge.

Here are some style highlights of Mackie’s style:

Humorous instructions:

Pack yourself a big lunch and go for a nice walk outside. Have a picnic and lie back and dream. Things are going to be so good now.

mackie meadow

Realism:

This icon a closer look will lead you to some explanations of features and practical tips. Go ahead and skip these if you need to leave the room in a hurry.

Anecdotes:

The dual-purpose mute/alt 3-4 switch is a Mackie signature. When Greg was designing our first product, he had to include a mute switch for each channel. Mute switches do just what they sound like they do. They turn off the signal by “routing” it into oblivion. “Gee, what a waste,” he reasoned. “Why not have the mute button route the signal somewhere useful, like a separate stereo bus?”

So mute/alt 3-4 really serves two functions—muting (often used during mixdown or live shows), and signal routing (for multitrack and live work) where it acts as an extra stereo bus.

Want to develop your own distinctive style?
Here are a few considerations:

Humor: Everyone likes humor. Apply with extreme care, however. Humor and wit are almost impossible to capture in translation, so only use them if you’re writing for a local audience. After all, what’s funny in the U.S. might not be funny in Iceland, or Turkmenistan, or Japan. Plus, humor is hard to get right. It takes writing, rewriting, whittling, and gumption. And sometimes, it’s not appropriate—don’t use humor in precautions, or in anything that may have legal ramifications. Also, sarcasm may sound funny in your head, but it usually just comes off as mean.

Despite the drawbacks, humor is sometimes the most memorable way to make a point. You can talk about capacitors until you’re blue in the face, but make people laugh and they’ll remember it.

Some tips on writing funny:

Set the tone: Your writing can be serious, authoritative, journalistic, friendly, humorous, or anything else you’d like. As a writer, you dictate the tone. But don’t change halfway through your document. Find one you like and stick with it.

Addressing the audience: The classic writing conundrum: Can a writer say “you” when referring to the audience? Sometimes people avoid the second-person pronoun to achieve a sense of distance and impartiality—especially on scientific topics. But if you are telling readers what to do, “you” and “your” is perfectly acceptable. In fact, when used purposefully, the informal “you” sounds more natural and encouraging.

Ex: “How to upload images onto your computer” vs. “Uploading images to a computer.”
Ex: “Be careful when you pull the wire from its connector” vs. “The wire should be pulled from the connector carefully.”

Ultimately, the choice is up to you.

Using contractions: To use contractions or not to use contractions? That’s the question. We have the answer: ‘Tis nobler to use them. Contractions shorten your sentences and improve the overall flow. If you doubt us on this point, try reading a paragraph without contractions aloud. It sounds unnatural. Swap in contractions and the paragraph sounds human again.

Short paragraphs are key: The rule of a well-formed, five-sentence paragraph is suspended in tech writing. You don’t need theses or topic sentences for manuals, and you don’t need long paragraphs to defend your assertions.

You can start a new paragraph whenever you start a new thought. (See what we did there?) Readers like short paragraphs. Short is easier to skim. We’re fans of using short, declarative bullets to break up content into little readable chunks.

Internationalization: If you plan on publishing for an international audience, your manual will need to be translated, which is an expensive process. The right style will make the translation process much easier. Some general style tips are the same: It’s even more important to limit your vocabulary to simple/common words. But when writing for translation, avoid jokes and idioms (they don’t translate well), use contractions in moderation, and be consistent with your phrasing. This tutorial, for example, would be very hard to translate into another language. We’ve used a lot of colloquialisms and idioms, quite a bit of of creative language, and we didn’t bother to limit our vocabulary. That’s a decision we made to keep this (long) tutorial both informational and engaging. These are the kinds of tradeoffs you’ll have to make as a writer.

There’s enough nuance to internationalization to fill a book, so check out The Content Wrangler.