Should you add screenshots to documentation?

Screenshots in documentation can be a contentious topic — some people really like them and think they add a lot of value, while others dislike them due to the maintenance burden and accessibility issues.

As a technical writer, I avoid adding screenshots to documentation as often as possible. In my mind, an outdated screenshot is one of the fastest ways to lose customer trust, so if I’m not confident I can maintain the image, I don’t add it.

But that approach might be too rigid and avoidant. What are the advantages and disadvantages to adding screenshots to documentation?

Why screenshots are bad

Screenshots in documentation can have a lot of problems:

However, these are mostly implementation problems. It’s possible to have screenshots in documentation without these problems.

Why screenshots are good

Screenshots and images in your documentation can serve some helpful functions:

Indeed, the Baymard Institute performed user research about SaaS products and found that 35% of SaaS Sites Fail to Make the Service’s UI Sufficiently Prominent to Prospects, making it harder for potential customers to learn more about the product. The findings apply to a product’s entire website presence (beyond the product documentation), but it’s important to keep in mind when deciding whether to add screenshots.

In light of those findings, it’s unfortunate that SaaS products typically update the UI constantly, making it especially hard to maintain accurate screenshots.

But these are some real advantages to providing screenshots in your documentation. So how do you add them while still avoiding the problems?

Identify the purpose of a screenshot

If you focus on the purpose of a screenshot in product documentation, you can identify a few situations where screenshots make sense:

In other cases, a screenshot might function as filler and not provide much of a function while still being difficult to maintain. Don’t add screenshots in these cases:

You also don’t want to provide screenshots to support text that describes every element on a specific page, because you don’t want to write documentation that only describes the user interface 1.

Make screenshots accessible

Whenever you add a screenshot, make it accessible. Accessibility of images is relevant for lots of different people:

If critical content is only available by looking at an image, it isn’t accessible to any of those people. Therefore, make sure that a screenshot isn’t the only way to gather important information.

You can start improving image accessibility by writing useful alt text. Refer to Microsoft’s excellent guide, Everything you need to know to write effective alt text.

You also need to consider the file size of any image that you add to your documentation, because image size can affect page load. Compress your images using a tool like (or others compiled by Smashing Magazine) before adding them to your documentation.

If you want, you can work with a translation service to localize images in your translated content as well, but you can also use other approaches to help make them accessible to folks who are reading your documentation other than the language your content is written in, such as by simplifying your screenshots.

Use simplified screenshots

Being intentional about adding screenshots to your documentation helps reduce the maintenance burden because you have fewer screenshots to maintain. But if you use simplified screenshots, you can reduce the maintenance burden further.

A simplified screenshot is a screenshot modified to obscure or remove content irrelevant to the purpose of the screenshot. Anton Bollen introduces the idea in his excellent article, Simplified graphics: Meet the new design style for technical communication.

For instance, you might provide a screenshot with some content blurred out, to help readers focus only on the relevant portion of the image.

Simplified graphic of the Google Docs navigation menu, where I drafted this blog post, with the title and some menu items obscured with gray rectangles. The visible menu options are File, Edit, View, and Insert.

While they might take a bit longer to make, simplified screenshots don’t need to be updated as frequently because you can obscure parts of the UI that are irrelevant for your task, unavailable to users with specific roles or permissions, or that might otherwise be confusing.

With a simplified screenshot, it becomes outdated at the same time as your text content, so you can update them both at the same time—rather than your image becoming outdated sooner because some other part of the interface changed.

Automate screenshots

If you’re committed to providing screenshots and have a robust docs-as-code pipeline, you can also consider automating screenshot creation and maintenance.

Simon Willison wrote and released a tool called shot-scraper which you can use to automate taking screenshots of webpages (and by extension, web applications). I haven’t used it, but I can envision designing a screenshot pipeline that works as follows:

  1. Attach a hook to a UI component that you use in a screenshot.
  2. If the code changes, prompt the tool to automatically take a screenshot in a demo environment.
  3. Compress the resulting image.
  4. Create a PR to add the new image to the documentation, replacing the old image.

Of course, componentized UI code means that this could be pretty difficult to instrument on a large scale (the only scale at which this would be necessary), but depending on your code base and technical skills, this might be feasible for your documentation.

Intentionally add images to your documentation

If you have a strategy and a process for adding and updating images in your documentation, you can avoid the pitfalls of screenshots in your docs and bask in the advantages.

  1. In rare cases, you might be writing UI reference content, such as when documenting critical workflows for a process where the UI has just had a major update and buttons have moved around, or if you’re documenting software for users that have never used software before. But otherwise, if you find yourself writing content that describes the available buttons on the UI, you might want to consider your audience more fully. ↩︎