Always outline
Outlines are a necessary part of writing. Period. Outlines are like a roadmap. They give you direction; they tell you where to go. Working without an outline is like trying to get from California to New York and only knowing you need to go east.
Put yourself in the place of the audience
Try to imagine things from your target audience’s point of view. Anticipate where your audience might have questions or how they might logically approach a task. Organize accordingly.
Be task-oriented
People read manuals because they are trying to figure out how to do something. Organize the body of your manual by activity, like “Quick Startup Guide,” “Troubleshooting,” “Replacing the Ignition Switch,” or “Using your Samurai Sword for Zombie Defense”—whatever task you think your reader might be interested in accomplishing.
Use lists
People love lists. On the internet, lists are almost as popular as cats. Unfortunately, we’ve yet to find a legitimate way for non-veterinarians to integrate cats into technical documentation (oh, we’ve tried). Lists, though, are a go. Whether numbered or bulleted, short lists are easy to understand and highly skimmable.
Not sure what sort of sections or subsections might be appropriate for your manual? There are lots of ready-made templates available on the internet. Reference them, but resist the urge to use them completely. Design your own structure. Take a look around at other manuals in a similar genre. Figure out what you like and what you don’t like about them. Use that information to make your manual better.
Writing useful instructions
We’ve been writing instruction manuals for years. One of the toughest lessons we’ve learned is that great instructions don’t happen on the first try. They come after trial-and-error, experimenting, and rewriting.
Sometimes, readers fail in ways that you can never anticipate. We learned that one the hard way. On a PowerBook G4, the optical drive connector is extremely hard to see. Our writers had a hard time explaining how to get the drive off without breaking the connector. When we published the guide online, someone used the guide and our instructions broke his computer.
After we apologized profusely, we rewrote the guide. And then we rewrote it again. And again. Until it was perfect. Here’s the final version of the rewritten text:
We learned from that experience. Now, we don’t wait until people break their stuff to rewrite our instructions. We solicit feedback from our users right away. When we released repair kits for Xboxes and PS3s, we asked purchasers to give us feedback on the instructions. Then we used their feedback to rewrite our guides. We’ve also integrated a comment feature in our guides, so users can share with each other where they ran into trouble and how they overcame the obstacle.
Find some way to get feedback on your instructions. You don’t need a web site to do it. Being on the receiving end of negative feedback is one of the toughest things you can do—but it is also the most important thing you’ll do for your writing. Bribe friends and coworkers for feedback, if you need to. Cookies, alcohol, or promises of babysitting—whatever it takes.
Making this feedback public can be surprisingly productive. Our readers tell us that the comments on iFixit manuals are often just as useful as the instructions themselves.
Organization
The nice thing about writing instructions is that they’re easy to organize. Just arrange things in the order they need to be done. We’ve found that step-by-step instructions with high-resolution pictures, diagrams, and videos are the most effective way to design instructions. Bulky paragraphs aren’t necessary if you let visuals do most of the talking.
When it comes to instructions, an ounce of preparation prevents a pound of frustration. Here are some great things to tell your readers before they start working:
- Difficulty level: Novices should go into a procedure knowing how hard it’s going to be.
- Time required: No one likes to figure out four hours into a task that it’s going to take four more hours. Especially if they needed it done 30 minutes ago. Make sure the estimated time takes into account the time involved for any prerequisite disassembly. If you’re an expert and you’re writing for a novice audience, assume it’ll take them anywhere between 20-50% longer to perform the same task. Account for that discrepancy in your time estimates.
- Materials required: If tools, parts, and materials are required, list them up-front.
Intelligent content reuse
When you’re writing a lot of instructions for a single device or machine (or lots of similar devices), reusing content saves a lot of time, work, and space.
Complicated tasks require a lot of dependent procedures. For example, whether you are changing the brake pads on your car or rotating your tires, both tasks require you to remove the wheels first. We like to call dependent tasks—like removing the wheels—prerequisites, because completing the procedure is required before you can go on to complete the whole task.
Reuse prerequisite tasks instead of rewriting them every time they appear in a manual. Most print manuals put prerequisite guides in a single place and ask readers to flip back and forth between the sections. So, the prerequisites are listed as a step.
- Step 1: Put your right foot in.
- Step 2: Remove the wheels. See pg. 34.
- Step 3: Put your right foot out.
When you finish with the prerequisite task, you flip back to the original instructions and move on to step three—like a convoluted Choose Your Own Adventure book. Flipping back and forth between sections isn’t terribly convenient, but that’s the best you can do on paper. On fancy computers, however, you can do a whole lot better.
Don’t treat computer manuals like print manuals. Doing so imposes unnecessary limitations on a far more advanced technology. Instead of asking readers to click back and forth through different web pages for prerequisites, integrate prerequisite guides directly into the tutorial. That way, all the instructions your readers need are on one web page.
For example, here’s an iFixit guide for removing a MacBook battery. The battery removal guide is a prerequisite for the RAM replacement guide for the same computer. You can see that the first two steps of the MacBook RAM guide are actually the steps for removing the battery. Instead of asking our users to click back and forth between individual procedures like you would in a printed book, the Dozuki software lets us list them all on the same page for a seamless user experience.
Many publishing platforms allow you to intelligently reuse content, labeling some procedures as prerequisites for automatic insertion into the instructions that require them.
Chapter 7
Chapter 9