Five Easy Ways to Improve Your Docs: Part 3, Death to Screenshots!

When assessing technical documentation for an editorial project, one of the very first things I make note of is the way in which screenshots are used. When I then say that one of the first things I will do in the project is strip out all those screenshots and replace them with text, the response is usually one of incredulity. “How can you have documentation without screenshots,” is a common response, as is “but some people are visual learners.”

Both of these things are very true. There is certainly a place for screenshots in technical documentation, and good documentation should consider different approaches to providing information. But all too often, screenshots are inconsistently and poorly used as illustrations, and have a tendency to devolve into a very lazy approach to documentation in which a screenshot and a few words of syntactically cryptic description are considered sufficient for providing information. And whatever advantages screenshots may afford for situating the user within the interface and rapid creation for documentation, consider also their disadvantages:

• They need to be updated with every iteration of the interface
• They break the cognitive flow of the reader, who has to switch between verbal and visual reading modes to interpret their content
• They are impenetrable to screen readers, and thus reduce their information potential to zero for visually-impaired users
• They cause tremendous bloat in the size of the documentation in all publishing formats
• They can turn a simple task into the scroll of death

One example from a recent project might illustrate the problematic nature of screenshots. With screenshots, the PDF version of the documentation ran to 1200 pages, and was around 150MB in size. When the PDF was generated from the wiki, it took almost fifteen minutes, and on occasion would crash the rendering engine. Within the documentation the use of screenshots was haphazard at best, but there were examples of tasks with around twenty steps that ran to almost a hundred pages, in part because of the way screenshots were used to (usually) illustrate every step and substep. And then there were the screenshots themselves, some dating back two generations of the product to interfaces of bygone days. By eliminating 90% of the screenshots, and updating the remaining ones, I was able to reduce the PDF to 800 pages and 29MB, and most tasks could be taken in with a glance. And best of all, it could be generated with confidence every time.

All that said, there are times when I think a screenshot is a great communications tool, for example In overview topics for the user interface, where you can establish the names of interface controls that you will use in text descriptions in other topics, and as illustrations for interface controls that don’t have labels, and which defy easy description. Whatever situations you use them in, a few best practices can substantially improve the way you use screenshots in your docs:

• Resist the urge to illustrate every step of a task with a screenshot. These interrupt the reader’s flow and bloat the documentation.
  
  
• Reserve the use of large interface screenshots for keystone topics that introduce readers to substantial product functionality
  
  
• Always provide a text caption or lead-in like “This screenshot shows . . . .” to guide the reader’s understanding of what the screenshot illustrates
  
  
• For illustrations of individual interface controls, use a system where you can refer to the same screenshot in an image library from within topics, rather than having each instance of the screenshot as an attachment to the topic
  
  
• Consider that a video embedded in an online version of a task topic might be a better way to illustrate a complex process

In his essay “Rhetoric of the Image,” the French literary theorist and cultural critic Roland Barthes argued that, in the case of news photographs, the captions served as anchors to the images, helping to fix the sometimes ambiguous meaning of them, a kind of literary supplement to the image. The same holds true of screenshots. Too often, they appear as supplements to the text, and only serve as indicators of the text’s inherent weakness, its lack of communicative content. Instead, screenshots should be used to clarify the meaning of the interface, with the supplementary text fixing the meaning of the interface elements. Keep this in mind as you consider whether to use screenshots in your docs, and I think the result will be that while they are very rare, they will also be very valuable.