Chapter 5


Writing never takes place in a vacuum (unless you’re literally in a vacuum, which would be incredibly uncomfortable). When you’re writing a manual, you’re always writing to someone. Figure out who that is. The more you know about them, the better your writing will be.

Optimize your manual to match the target audience’s expertise. The Books for Dummies series, for example, has successfully targeted one narrow audience: the clueless newbie. For Dummies publishers have a book on everything from writing résumés to coaching children. Each one features diagrams, illustrations, extended explanations, context, and basic tips.

Auto Repair for Dummies has a whole chapter dedicated to changing your car’s oil. It covers what oil does in the car, the pros and cons of synthetic oil, and instructions—15 pages of ‘em. If the book was entitled Auto Repair for Experts, however, that whole chapter could be boiled down to a single sentence: “Change the oil.” Unless they’re changing the oil on a supercar, no car expert will need 15 pages of instruction for an oil change.

Knowing your audience means knowing what to include and what not to include. It means you know how many steps it’ll take to explain something to them. It means you know how long your manual is going to be and what sort of language you can get away with using.

Here are a few things to keep in mind:

Reading level = writing level

You shouldn’t write over your audience’s head. You also shouldn’t write drastically under it, although in our experience this is rare.

Flesch-Kincaid Readability Tests are the most common way to ascertain a text’s readability. Flesch-Kincaid scores ease of reading on a scale of 0-100, with 100 being the easiest to read. Another Flesch-Kincaid test estimates reading level (K-12).

To show you just how wide manuals can miss the mark, we decided to test a manufacturer manual for a popular product—Apple’s MacBook Pro—on the Flesch-Kincaid scale. The Apple user manual scored an abysmal –2.2 and required a reading grade level of 24. (In case you were wondering: no, grades don’t go that high.) To put this in context, Shakespeare’s Macbeth is at an 11th grade reading level.

Here’s a safe rule of thumb: A user manual shouldn’t be more difficult to read than Shakespeare.

The Bard

iFixit’s repair manual for the same device scored at a fourth grade reading level. The lower the reading level, the more likely your readers will be able to understand what you’re saying.

Not sure how to gauge the reading level of your writing? You can use sites like The Readability Test Tool to measure readability on existing web sites. Word and Excel already have readability tools built into them—they just need enabling.

Existing knowledge

What can you assume your audience already knows? Technical writers often forget what their audience knows and, especially, what they don’t. Mechanical engineers sometimes write manuals that sound like they are written for other mechanical engineers—but if the target audience isn’t super tech savvy, then rambling on about shear load, helical gearing, and kinematic chains without an explanation is a problem.

Military organizations are amazingly bad at this. They have so many acronyms that you have to spend months learning them all before you can communicate with anyone. Here’s an example from an Army Shipboard Operations manual:

a. Emergency Training. Emergency requirements or training necessary for imminent deployment usually will come from DA through a MACOM such as FORSCOM. Army aviation units will receive the higher command's assistance in scheduling ships and other resources.

The standard practice in technical writing is to spell out an acronym on its first usage, putting the acronym in parentheses. This ensures clarity for all readers.