Images: The Good, The Bad, and The Ugly

Can we talk about a painful subject? Yes, it’s painful, but if we want to get past the pain and the discomfort, we have to discuss it. It’s pictures. And not just any pictures, but the ones technical writers put in user guides to make them more vivid, and to help illustrate the points they’re writing about. Let’s face it, sometimes those pictures confuse more than they elucidate. They’re either too complex or too simple, without the appropriate amount of thought put into making them right.

Contrary to the title of this article, let’s start with the ugly. Ugly, in this context, does not refer to the aesthetic qualities of the images a technical writer places in a document (though aesthetics are important). Rather, ugly refers to the appropriateness and the amount of detail in those images. Before you start to shudder, let’s consider the prime example of ugly: the architectural diagram.

Now, architectural diagrams aren’t ugly per se. They serve an important engineering purpose, but they should never appear in user or training guides. If there is one immutable principle here, it’s that users of complex software and hardware systems will tune out quickly when confronted with a  diagram that attempts to explain the totality of a system in one giant picture. Not only that, but when you try to fit an architectural diagram onto an A4 or A5 page, none of the complexity is legible. It’s like trying to identify the make and model of a car from several thousand metres above, whilst travelling in an aeroplane at cruising speed.

Next, let’s say a few words about bad images. Bad images are a bit more subtle in that they’re not overly complex, but rather – in many cases – they’re too simple. A picture of a cylinder with an arrow pointing to a box may make sense to someone who understands the notion of extracting data from a database, but to the user trying to understand a process, it’s nothing but a cylinder and a box. In other words, the technical writer assumed the reader was familiar with Visio-style objects. We all know what happens when you assume.

This takes us to our happy place: the good image. Helpful pictures are those that complement the text by providing visual examples that illustrate. They needn’t be simple pictures, either, but rather provide the right amount of detail to help the reader grasp a principle, a process, or even an event. For example, a section of a manual needs to explain to the user what happens upon clicking a button on a web page. A good image would include, at a high level, each of the events that occur as a result of the button click.

Another type of good image is what I call ‘badge-driven.’ You may need to include complex diagrams in your user guides, but instead of simply placing them with no commentary, you identify each step in the process with little numbered badges, like the ones you see on smartphone displays to indicate the number of unread messages in your inbox. Under the image, you then explain each numbered badge in an easy-to-read table. The result is the best of both worlds; you’re able to present complex material, but also give the appropriate amount of description so the reader isn’t confused by a bunch of boxes with arrows.

When thinking about images, always consider your audience and whether the images help or hinder your message. Your readers will thank you for the extra effort.