How to audit your docs and marketing for outdated screenshots
This is a one-time sweep. You list every screenshot you publish and every place it appears, decide which to check first, then hold each one up against the product as it is today. The date on the file won't tell you which ones are wrong. The product will.
Why sorting a documentation audit by date fails
Most content audits start by sorting pages by "last edited" and reviewing the oldest. For screenshots that sends you to the wrong place. One study tested exactly this. Researchers studying VS Code's documentation took the median time between updates for screenshots that had been fixed, 297 days, and flagged every screenshot older than that.
- The 297-day rule flagged 70.3% of VS Code's screenshots as outdated.
- They checked 154 of the flagged screenshots by hand. Only 8 were actually outdated.
An old screenshot of a screen nobody has touched is still right. A screenshot taken last month is wrong if the screen changed last week. There is more on why page age is a weak signal in our write-up of that study, and a broader summary of what the research says about product screenshots.
Wikimedia's documentation toolkit reaches the same conclusion for whole pages. Its freshness check asks reviewers to score content from 1 (fresh) to 5 (completely outdated), and warns that "last revision date doesn't correlate directly with freshness."
1. Scope the audit
Screenshots live in more places than the docs site, and different people own each place. Write the list of places before you look at a single image.
- Docs site and help center. Getting-started pages and task guides carry the most.
- READMEs and other Markdown in your repositories. Contributing guides, wikis and example folders count too.
- Homepage. The hero image is the screenshot most people see.
- Pricing and feature pages. These often show plan names, limits and settings, which change more often than layout.
- Sales deck. It lives in a slides tool, not your repository, so no search of the code will find it.
- App store listings. Each store, each device size and each language is a separate set of images.
The last four are marketing screenshots, and they are the ones a docs-only audit misses. Name an owner for each place now. You will need them in step 5.
2. Build the inventory
Make a spreadsheet with one row per embed, not one row per image file. A screenshot used on three pages is three rows, because each page can need a different fix, or none.
| Column | What goes in it |
|---|---|
| Image | File path or URL |
| Embedded in | Page URL, slide number, or store listing and slot |
| Product screen | Which screen and state it shows, such as "Billing settings, admin, dark mode" |
| Owner | Who can change that page or file |
| Traffic | Monthly views of the page it sits on |
| Image date | Record it, but don't rank by it |
| Verdict | Filled in during step 4 |
The "Product screen" column is the one that makes the rest of the audit work. It lets you join the inventory to a list of UI changes in step 3. Wikimedia's toolkit also advises against a catch-all notes column, because you can't sort or filter on it. Give each judgment its own column.
To fill the sheet:
- Repositories. Search the source for image syntax and image file names, for example git grep -nE '!\[|<img|\.(png|jpe?g|gif|webp)'. Each match is a row.
- Published sites. Crawl the site and collect every img source, including images set in CSS. A CMS often stores images outside the repository, so the crawl catches what the search misses.
- Decks and store listings. Open each one and list the images by hand. There is no shortcut.
3. Rank what to check first
A large product can have hundreds of rows. Rank them with signals that point at real changes, and use the image date only to break ties.
- Screens touched by recent UI changes. List every screen that changed since the last time anyone checked. Release notes, merged pull requests, design tickets and the changelog will name them. Every inventory row showing one of those screens goes to the top. A UI change is what makes a screenshot stale, so this is the strongest signal you have.
- High-traffic pages. Your analytics will name them: usually the homepage, pricing, and the first few getting-started pages. Wikimedia's toolkit ranks pages by page views and by how many other pages link to them, and the same two numbers work for screenshots.
- Pages reached from support tickets. Search tickets for links to your docs. When support agents keep sending people to a page, those people are trying to follow it step by step. That is where a wrong screenshot does the most harm.
- Reports from readers. Search your issue tracker and feedback forms for "screenshot", "outdated", "doesn't match" and "can't find". In the VS Code study, the researchers found their 210 reports by searching for "update screenshot" and "outdated screenshot". Of the 44 they sampled, 36 came from people outside the docs team.
Plone's documentation shows how long this can sit. In January 2024 a docs maintainer opened issue #1611 asking for current screenshots of both of Plone's interfaces, and for a check that flags when a new capture differs from the previous one. The issue notes that Plone 5's docs once had such a feature, which has since become unsupported. When we checked on 15 November 2026 it was still open, and the proposed first trial was a single page with four screenshots.
4. Compare each one with the product
Open the product on the same screen, in the same state the screenshot shows: the same role, plan, sample data, theme and window size. Then go through the image and ask:
- Is every label, button and menu item in the image still there, with the same name?
- Where the text says "click", is the thing to click in the same place?
- Does the path to reach this screen still work as the page describes it?
- Does the image show an old logo, colour, font or product name?
- Do plan names, prices and limits in the image match what you sell today?
- Does the text around the image still match the product?
That last question matters more than it looks. In the VS Code study, 24 of the 44 sampled fixes changed the text as well as the picture.
Give each row one verdict:
- Current. Matches the product.
- Cosmetic drift. Looks different, but a reader following it would still succeed.
- Wrong. A reader following it would fail, or a buyer would be misled.
- Gone. The screen no longer exists.
Text has an advantage here that pictures don't. Wen Siang Tan, Markus Wagner and Christoph Treude built a tool that finds references in documentation to code that no longer exists. In the 1,000 most popular GitHub projects, 28.9% of the projects they analysed (265 of 918) had at least one document with an outdated code reference. Their follow-up packages the check as a GitHub Action that scans docs on each pull request. It works because the tool can match a name in the text against the code. A screenshot has nothing to match, so you still have to compare it with the product.
5. Record and fix
- Fix "wrong" first, in rank order. On pricing and feature pages, treat any wrong plan name or price as urgent, whatever its rank.
- Retake from the current product. Use the same screen and state you wrote in the inventory, so the next audit can compare like with like.
- Delete what adds nothing. A screenshot of a screen the text already describes well can go. It is one less image to keep right.
- Send each owner their rows. The people who own decks and store listings fix them, not whoever ran the audit.
- Keep the sheet. It is the starting point for the next audit, and the "Product screen" column tells you which images a future UI change will break.
After the sweep
An audit tells you what is wrong today. The next release starts the drift again. To stop them going stale again, the screenshots have to come from the product whenever it changes, not from a person remembering to retake them.
That is what Screenery does for the screens your end-to-end tests can reach. Your tests take the screenshots in CI. Screenery publishes each one at an @latest URL that a push on the default branch moves, so a docs page or README that embeds the URL shows the newest capture. On a pull request it comments with which screenshots changed. It doesn't reach a pasted image in a sales deck or an app store listing. Those rows stay in your sheet and still need an owner.
Sources
We opened every page below on 15 November 2026 and checked each number on this page against it.
- Tang, Yan, Liu, Meng and Zhong, "Detecting Outdated Screenshot from GUI Document", ACM TOSEM 35(5), article 133, April 2026
- The same paper, authors' preprint (PDF)
- Tan, Wagner and Treude, "Detecting outdated code element references in software repository documentation", Empirical Software Engineering 29, article 5, 2024 (open access)
- Tan, Wagner and Treude, "Wait, wasn't that code here before? Detecting Outdated Software Documentation", arXiv preprint 2307.04291, 2023
- Wikimedia Documentation Toolkit, Collection audit, including its Survey, Prioritize and Assess steps
- Plone documentation, issue #1611, "Automate screenshots and videos"