Search results

Rethinking the Importance of Screenshots, Diagrams, and Other Visuals

by Tom Johnson on Aug 10, 2007
categories: technical-writing web-design

I used to think screenshots weren't necessary when it was obvious where buttons and other links were located. For example, if I wrote something like "Click the Subscribe to the RSS Feed RSS Feed link in the sidebar to subscribe to this blog's RSS feed," you'd think that people could easily follow this instruction.

However, after watching user behavior, I have changed my mind. I now think screenshots are important to include even when interface elements aren't necessarily hidden. I'm not saying each step needs a screenshot, but we should be more generous than stingy with screenshots, graphics, diagrams, and other visual elements.

Kim Nathans left a really persuasive comment on a previous post. She writes,

I thought I was doing great with my screen shots, only providing them when their use would save me several dozen words. My boss was happy that we could cut down on maintenance costs because the screen shots are so quickly outdated by the addition of new features.

But then I got my first actual feedback from a new employee (Director of Development) and he was disappointed that I didn't include a pictorial storyboard of the process flow. It turns out that he didn't so much read any of my documentation as just glance at it. I started thinking about how many of the consumers of this documentation will be like him, and was depressed to realize that there will probably be a lot more like him than like me (a compulsive reader who will read every word in front of her face).

I've been googling (too much today) and have found that there are two sides to the “Screen Shot or Not” issue.

Tech writers (and their bosses) think that less is more.

Users think that more is more.

I asked a marketing intern in our office for his opinion, and he pulled out a very dog-eared and obviously well-used document that he had printed out. It was nearly all screen shots with certain UI items circled sloppily (like they'd used a mouse to do it freehand). He enthused for a couple of minutes about this being the most useful piece of documentation he's ever had, because he can quickly refer to it and easily find the steps he needs to take to accomplish whatever task it conveyed.

I also came across a study on learning using a 94-page manual versus using 25 flash cards. It turns out that people learned more quickly with the flash cards covering key ideas and hints, and no step-by-step instruction.

How depressing! I was hired as a “tech writer” but it turns out that users only want a pile of screen shots! I have to rethink all of this before I tackle this next documentation project. *sigh*

In going through the Visio tutorials that I mentioned in an earlier post, I realized they were heavily visual and conceptual. We tend to write task-oriented instructions, jumping right into steps. But if you look at Microsoft's instructions for their 2007 products, the writing is more conceptual and visual. At least with the SharePoint 2007 documentation, many topics have 4-5 paragraphs of explanations before they even get to steps.

I'm not saying steps aren't important, just that concepts are equally important. You can't train people to be power users by simply writing click this, select that, go here, click there. They have to understand concepts and processes.

In communicating conceptual information, it's extremely important to reinforce concepts with visuals. Not just screenshots, but diagrams. This is one reason I'm dipping into Visio more heavily. Diagrams, not just screenshots, help users understand concepts much better.

One problem with graphics is that they take time. It takes just as long to create compelling visual diagrams as it does to write instructions. With this post, for example, I'd like to include a graphic, but I ran out of time at the moment.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.