Chapter 7

Using other visuals

Videos, illustrations, diagrams and graphs work wonders when you want to explain exactly how something works and how to assemble or fix it. Even better, visuals allow you to be more concise.

Diagrams and illustrations

Diagrams and illustrations are a great way to give readers a big picture layout of devices, parts, and components. The more visuals you include, the fewer words you have to use. They are also especially good at breaking down hard-to-see or hidden elements, like the wiring schematic of a car.

Here’s an example diagram from a Mackie Onyx Analog Mixer, an extremely complex machine with lots of hookups, plugs, and doodads. This great diagram clearly shows what those plugs do:

Mackie Onyx diagram

Mackie diagrams are amazing. But in our experience, bad diagrams outnumber the good ones. Most of the time, diagrams fall short because they are not descriptive enough. Others are poorly rendered, too cluttered, or not augmented with enough written explanations. Imagine trying to put something together when the diagram looks like this:

helicopter diagram

Or, how about this?

bad diagram

When you’re in the midst of a complicated repair or installation job, bad diagrams won’t be helpful.

Video instructions

The only thing people love more than a picture is a moving picture. If you are publishing digitally, you can embed videos directly into your manuals. Pretty fancy, huh?

People are drawn to instructional videos. They mimic that one-on-one, expert/apprentice relationship that we all crave when learning something for the first time. Video instructions are so popular that YouTube has now become the internet’s default how-to authority for everything from computer repair to equipment setup to physics. A search for “how to” on YouTube’s video archives returns over 19 million hits. A single YouTube tutorial on how to fold a t-shirt in under 2 seconds has been viewed millions of times.

Videos can make learning easy, but—big warning—they are also easy to overuse or mess up. If your reader is looking for specific information, videos can be frustrating. No one wants to watch a 20-minute video when they’re only interested in locating a screw.

Weigh your options before you make video instructions your primary source of documentation. Most of the time, a single photograph or an amazing diagram will be more functional at identifying connectors, parts, and processes. And, unlike videos, photographs can do it at a single glance. Only use video when other visuals won’t cut it.


Use videos when…

If you’ve decided that video guides are the way to go, then apply the rules of writing to the editing room. Video guides should be concise, demonstrative, and clear.

We’ve filmed a lot video guides that can stand alone, but we’ve found that the most effective way to use videos is to embed them directly into online, step-by-step guides. Short video clips work very well alongside diagrams, photographs, and text to augment procedural instructions.

Frequent problems with video instructions…

Here’s our rule of thumb: in-manual videos should be no longer than 30 seconds per step. Sometimes just 3 seconds of video is enough to get the job done. The shorter the video, the better.

Icons and symbols

The first rule of any profession is to do no harm (especially since doing harm opens a company up to litigation, as we discuss in Chapter 9). So, make your best effort not to set people on fire or expose them to electrical shock.

Where harm is possible, say so. But here’s the rub: since most readers skim, you need more than bold lettering to grab a reader’s attention. That’s where icons and symbols come in handy.

Some manuals, like the For Dummies series, include 12 different icons that readers need to remember. No one will ever hold that many symbols in their head. Don’t use a dozen symbols when just a handful will do. We recommend, at the very least, using “Note,” “Caution,” and “Warning” as safety designations. Not all icons translate. So, be sure to use universally accepted icons, like a splat symbol, or those published by ISO or ANSI.

Warning bubbles