Learning How to Communicate Visually in Documentation

From my recent survey on why users can’t find answers in help, many users voted on the following reason:

  1. The answer is buried in a long page, but the user only spends 2 minutes max on a page scanning. (survey results)

The page may be 1,500 words long, but the user spends just a few seconds quickly scanning the page and misses the answer.

In an earlier post, I talked about using subheadings as a way to overcome the problem of page length. Subheadings are an excellent technique for facilitating scanning, but there’s another technique that is even more powerful: visuals. Visuals not only draw the user’s attention and focus, a good visual communicates meaning almost instantaneously.

I noticed this the other day as I pointed someone to an article I’d written. The article had a visual diagram. As soon as the person arrived at the page, he studied the graphic for several seconds and then started responding to the ideas — without even reading the article.

The lengthy text had taken a backseat to the reader’s focus and attention on the visual. I suspect most people looking at a page with a strong graphic do the same — respond immediately to the visual while ignoring the text.

Visuals engage the reader in much more powerful, immediate ways than walls of text.

Visuals engage the reader in much more powerful, immediate ways than walls of text.

There’s a reason our eye naturally moves to visuals: they’re the quickest and easiest way to understand something. We can process visual cues and meaning unconsciously in the blink of an eye, even before our conscious mind registers what’s going on (see Malcolm Gladwell’s Blink). Given this efficiency, it’s no wonder that visuals are the starting point for our attention — why waste time unnecessarily?

I noticed the power of visual communication last week. I brought home a diagram I’d created to depict a process I’d been writing about all day at work. I asked my 12-year-old to tell me what the diagram was trying to show. She studied it a minute, and then to my astonishment described with near exactness what I was trying to depict. I was floored.

Sample diagram showing a process (filler text)

Sample diagram showing a process. (I had to replace the real text with filler text due to confidentiality reasons.)

Where to place visuals

There are a few key places where visuals are key. When you’re introducing an idea, a visual in your conceptual overview makes a great lead-off image to an article, inviting the reader’s attention. Right from the start, the image pulls the reader into the text.

But the visual should be more than just an image. In documentation, a visual illustrates an idea, clarifying a process or concept in a meaningful way. You’re not just adding decorative images for the sake of breaking up text (although that’s not entirely bad), you’re adding images to instruct and teach the reader about new ideas. Illustrations make a point. We’re not talking about art and mood or color for the sake of art alone. Visuals are doing work to instruct.

While you’re instructing the reader with new concepts and ideas, you can leverage illustrations to reinforce the meaning. As soon as you leave the land of conceptual information, though, and are just listing steps to complete a task, there’s no need for concept diagrams or idea-rich illustrations.

In these supporting task areas, screenshots work well to provide more visual rhythm and interest. A screenshot may not teach the user a new concept, but the screenshot does provide follow through in showing the user how to execute on the concept.

What makes a good visual

When creating visuals, a lot of technical writers feel intimidated about their lack of artistic skills. After all, graphic designers can create much more spiffy, sharp-looking graphics.

Fortunately, the more minimal the graphic, the better. All of those graphic details just tend to get in the way. When you strip down the graphic to its bare bones, you draw more attention to the point of the graphic.

In contrast, if you include a lot of graphic detail in your illustrations, you risk shifting the focus to the artistic details rather than the point of the visual. Besides introducing a lot of distracting elements (Edward Tufte calls unnecessary graphics “chartjunk,”), creating more realistic, detailed art creates a lot of extra work for yourself.

For example, let’s say you need to depict a person crossing the street. You could download a fancy vector icon showing a person fully colored, with detailed hair, shading, and even facial features. The person may be wearing a suit or collar shirt and have other characteristics. It may be a great looking graphic, but now you’ve got more burden to keep up the same degree of artistic realism.

To go along with the vector graphic, you’ll need to also create a similar looking street, with shading and perspective. You’ll need to create a road with contours and texture. You’ll perhaps need some sky and surrounding elements. Before you know it, your meager attempt to show a person crossing a street has become a full-fledged artistic production consuming days of work and unnecessary labor.

And what will the result be? Unless you have a lot of artistic talent and command of illustration tools, the result will probably look somewhat unprofessional.

As an example, take a look at this quick reference guide I made several years ago. The vector icons clearly don’t match the visuals used elsewhere in the guide.

The people icons (from istockphoto) are clearly more polished than the rest of the diagram and artwork. The result is that it looks imbalanced and mismatched.

The people icons are clearly more polished than the rest of the diagram and artwork. The result is that it looks imbalanced and mismatched.

Instead of aspiring for realism, you’ll be more successful with visual communication if you follow a principle of minimalism. What are the minimum lines you need to communicate the idea? Rather than focusing on whether you got the shading right based on the angle of the sun, with minimalist illustrations the audience focuses only on the illustration’s meaning, because that’s the only element really available to evaluate.

Think about the walk signal when crossing the street. Here it is, in all its plainness:

The walk signal is a really simple graphic.

The walk signal is a really simple graphic. (By the way, I took this photo on the way to work in Redwood City, Calif.)

No need for fancy graphics here to get the job done. The walk signal is just a simple mix of rectangles and circles.

Cognitive load

In Graphics for Learning: Proven Guidelines for Planning, Designing, and Evaluating Visuals in Training Materials, Ruth Clark and Chopeta Lyons explain that removing distracting and non-essential elements of visuals can reduce cognitive load and help users focus on what really matters.

Here’s an image from their book that compares a photograph versus a line drawing in a car guide:

Using a line drawing instead of a photograph reduces cognitive load on the user by eliminating the non-essential elements of the visual.

Using a line drawing instead of a photograph reduces cognitive load on the user by eliminating the non-essential elements of the visual.

Clark and Lyons explain:

… in situations where the learner has little control over the pacing of the lesson such as in a short animated sequence (instructional control rather than learner control), simpler line drawings result in better learning than do complex realistic illustrations. On the other hand, more complex illustrations sometimes result in more learning when learners have unlimited time to study the graphic (Levie, 1987). Therefore, we recommend that you plan graphics at the lowest level of complexity that will support the instructional goal, especially when the content is new, there are complex visual discriminations involved, and when the materials are presented out of learner control. (Chapter 6)

In other words, graphics that have the lowest level of complexity often have the biggest impact on users who are pressed for time. But if your users have a lot of time to spend looking at visuals (I’m not sure who these people might be), go ahead and add more detail in the illustrations.

Overall, I think minimalist graphics are a win-win situation — easier to create, and more powerful for learning.

Tracing stuff is easy

Did you also know that if you need to create minimalist shapes, it’s really easy in Illustrator? Today virtually everyone has a camera phone. Take a picture of something you want to draw. Now bring that picture into Illustrator, put it on its own layer and increase the transparency. Add another layer and use the pen tool to trace it. Then fill it in with color.

Tracing objects in Illustrator is pretty easy.

Tracing objects in Illustrator is pretty easy.

Voila — in about 5 minutes, you’ve got an immediately recognizable shape, and if you took the original photograph, you don’t have to worry about copyright infringement (most of the time).

Art is fun

I think technical manuals would be a lot more engaging if each section opened with a visual diagram that communicated to the user visually rather than beginning with long textual explanations.

Visual techniques are totally within our grasp, but we’re often held back by assumptions about graphic design skills and professionalism. One element that might help overcome this fear is simply this: Art is fun.

Think back to your high school art class. Right now art is my daughter’s favorite class. You know why? Because she gets to create stuff — drawings from her own imagination.

Tech writing should be the same way. After all of those textual instructions, explaining and numbering with steps, and nearly dying of plainness, here’s a chance to let your hair down and get creative. Draw. Put on the headphones and turn up the music, and then just let your mind wander with a pencil and paper. This is the fun part of technical writing! Skipping this part in a tech comm career is like skipping art so you can take an extra math class.

The hard part is the concept, not the execution

When you start drawing, you’ll soon learn that the hard part isn’t the execution. It’s the drawing. This is what Don Moyer said during his presentation on visuals at an STC session a few years ago. The difficulty is figuring out how to depict an idea in visual form.

Here are some doodles I made tonight while brainstorming ways to show a “mission.”

Here I was trying to come up with novels ways of visualizing a "mission," which is a series of rewards a player must earn.

Here I was trying to come up with novels ways of visualizing a “mission,” which is a series of rewards a player must earn.

Even if you were to have a graphic designer at your disposal, to create whatever you wanted, you’d still need to give the graphic designer a sketch on paper illustrating the idea you wanted to convey.

Communicating visually is difficult in part because we do it so infrequently, Lyons and Clark explain. We’ve become used to relying on words — lots of them — to communicate ideas. But the more we exercise the visual dimensions of our brain, perhaps by frequently sketch-noting during meetings, or doodling, or even playing Pictionary, the more we develop an ability to communicate visually.

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

10 thoughts on “Learning How to Communicate Visually in Documentation

  1. John Tait

    There’s a great book called “Illustrating computer documentation” by William K Horton, which I recommend to everyone for its many examples.

    It’s out of print, but easy to buy second hand. It’s not just for computer documentation.

  2. Mark Baker

    I totally grock the power of visuals, and the importamce of minimalism in illustration, and the importance of design over execution.

    But it is not true of me that I am instantly drawn to a graphic on a page. Quite the opposite. My eye naturally skips over graphics — and headings — to follow the narrative line of the text. I will only go back and look at a graphic if the text demands it. And if the text does demand it, then I want it to be a graphic whose meaning I can take in at a glance. If I have to study the graphic to understand it, that breaks my flow in the narrative and I feel lost. (I always found Horton’s books virtually unreadable because of the amount of visual clutter.)

    I am probably with the minority in this strong preference for the narrative line. (And it is a preference for the narrative line, not for text per se — I love a good comic as much as anyone.) But I also worry about the conditions under which these studies are done. How do you create genuinely purposeful reading under labratory conditions?

    In any case, I think my point is: be wary of making your diagrams rivals for the reader’s attention. Text and graphic should work together. Along those lines, and in keeping with the minimalist principle, I think it is vastly preserable to create several simple graphics that build an idea rather than one complex graphic that sums up an idea. Summation is not exposition, either in graphocs or in text.

    1. Tom Johnson

      Mark, good point on creating smaller graphics that build an idea instead of one massively complex diagram. Re the feedback about being drawn to the text rather than to graphics on a page, I think you’re in the minority there. Of course there are many different kinds of graphics, and different contexts for reading, so generalization is difficult here. But the basic principle of combining text with graphics within the narrative flow tends to be a knockout combination for communication that too often gets overlooked in tech comm. However, I appreciate your point here about not over-prioritizing visuals over text. Visuals usually support the narrative flow of text. Thanks again for commenting.

  3. Fer O'Neil

    Regarding the idea of “leading-off” with a graphic when introducing a concept:
    “Right from the start, the image pulls the reader into the text.” I think of this as the “blog style” of writing, and haven’t necessarily thought of using this style for technical documentation—but I’m open to it. Do you really think it is ok to begin a technical document (e.g., a web page available as online help) with an image versus more typically beginning with the first step of the solution (and as Mark says, to make the text and graphic work together)?

    Second, unrelated question, regarding “the more minimal the graphic, the better”—I realize you are talking about graphics and not “screen shots” per se. However, I’ve been thinking about graphics more generally lately (how to present screen images) and I’m curious what others think about “stripping down graphics to their bare bones” and whether this could include UI images? For instance, if the UI of a product has many elements to it, but you only want to focus on one specific element/section, if you include enough contextual UI elements to orient a user, is it preferable (“draw more attention to the point of the graphic”) to have a wireframe-like image as opposed to an exact UI representation?

    1. Tom Johnson

      Fer, thanks for commenting. Re leading off with graphics, I didn’t mean suggest putting an image before you get into any text at all. I mean that as you’re explaining concepts, which is usually common in an overview section, it’s a good idea to interweave concept diagrams into those conceptual sections. I definitely support integrating graphics with the narrative flow of the content.

      Re using wireframes instead of screenshots, way too much work. It’s so much easier to take a screenshot, add a callout, and be done. I can’t imagine recreating the screenshot as a wireframe. Are you trying to address translation issues?

  4. Jason Owen

    Another book for everyone to consider is The Napkin Sketch Workbook by Don Moyer. This workbook provides information about how to create simple sketches, even if you have no artistic ability (like me). With some basic command over a graphic illustration program, you can transfer napkin sketches to computer files.

  5. Sandeep Virmani

    Hi Tom,
    Nice Article, thanks for emphasizing on the visual communication. I work as a visual graphic designer for product documentation and too believes that simple visual communication can do the trick without misguiding the users. I have been trying hard to innovate new methods for visual communication for our documentation and have been focusing on info graphics for a while, trying to invent possible visual outcomes which can communicate effectually and can complement the documentation content.

    How much graphics can complement, the content or confuses the user is still part of my research, let me know if you have come across the same query and can update my further.

  6. Reuben Borg

    Infographics are also really useful in combining the effectiveness of graphics with text. Infographics can be used to convey a more complex message which would otherwise require long text.
    Downside – Can take quite long to plan and create an effective infographic.
    Reuben – http://reubenborg.com


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>