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:

• Outdated screenshots can cause customers to lose trust in documentation accuracy.
• Pages load more slowly when they have a lot of screenshots compared to pages that only have text.
• Screenshots can replace step-by-step instructions, losing an explanation of why you might perform a task and replacing it with an image of how or where.
• Screenshots often have no or poor alt text, making them inaccessible to those with low or no vision.
• Relying on screenshots can lead you to write documentation that only describes the UI, instead of what you can do with it or what the data visible in a dashboard means and where it comes from.

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:

• Make it easier for readers to scan to a relevant part of the content.
• Provide a visual frame of reference for people reading the documentation without using the product at the same time.
• When used correctly, they can supplement confusing task steps.

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:

• Make a confusing page clearer by adding context to it.
• Give someone a sense of how a page might look when it has data in it.
• Walk users through a task that traverses multiple different pages in the UI.

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:

• For every step in a task.
• To provide visual interest without a reference in the text.

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 ¹.

Make screenshots accessible #

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

• A data analyst with low vision that keeps the documentation site zoomed in at 400%.
• A sales engineer using a mobile hotspot to work at the airport.
• A sysadmin visiting family in a rural area that just got woken up by an urgent page in the middle of the night.
• An engineer using a localized version of your product in their own language.

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 compressor.io (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.

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.

• Add screenshots to the documentation only when they’re relevant and useful.
• Make screenshots accessible, so even if they aren’t there, the content is still useful.
• Use simplified screenshots to ease the maintenance burden and increase the relevance.
• Consider automating screenshots if you have the resources.