How we maintain screenshots in our product documentation

In brief

Our docs-as-code workflow is being extended to product screenshots. This is how we are setting up LaunchBrightly, GitHub and automated visual audits to keep our documentation in sync with our product.

Summary

  • Screenshots go out of date quietly - in four LaunchBrightly audits of our docs during 2024, between 23 and 69 screenshots each time, out of 264 to 328 checked, no longer matched the product
  • The main screenshot on each page will get a recipe - a reusable set of browser steps that signs in to a demo organization on our staging environment, opens the right view and captures it, so the image can be rebuilt whenever the product changes
  • Updated screenshots will arrive as GitHub pull requests - they target the staging branch of our documentation repo, and a check fails any pull request from the LaunchBrightly app that changes more than screenshot files and image lines
  • Nothing reaches the live docs until we promote it - screenshot updates wait on staging until we move changes from staging to production ourselves. Read the Tallyfy product guides

Documentation has a funny habit of becoming outdated the moment you publish it.

At Tallyfy, the product changes all the time. Features change, interfaces improve, navigation moves around, phrases change, charts expand.

Our engineering team already manages documentation as code, using Markdown, GitHub, and an automated publishing pipeline. That gives us version control, proper pull requests, code reviews, and a repeatable deployment process.

But there was one part of the documentation that didn’t really behave like code: screenshots.

Unlike text, screenshots don’t (as easily) tell us when they’re outdated. Four visual audits of our docs in 2024 checked between 264 and 328 screenshots apiece, and each one turned up between 23 and 69 that no longer matched the product. At this point, it’s tempting to use fewer of them, or avoid them altogether.

But that would be a mistake. Research in the Cambridge Handbook of Multimedia Learning shows that people learn and remember more when words and pictures work together. And that makes sense: seeing where to click beats reading three paragraphs explaining it.

So we set out to remove the headache of keeping screenshots up to date.

We’ve been using a screenshot automation platform (LaunchBrightly) to automate product screenshots for some time. Recently, we started upgrading that setup to use its native GitHub integration, which brings screenshot generation, visual auditing, and updates directly into our existing docs-as-code workflow.

The challenge with screenshots in a docs-as-code world

A Git-based documentation workflow works well for text.

You change a Markdown file, open a pull request, review the diff, merge, and your build process deploys it. Git tells you exactly what changed, when, and why.

Visuals are a little different.

Imagine we rename a button in our product. Updating the documentation text is manageable. But what about the 7 screenshots across 5 help articles that still show the old version of the button?

Finding them is hard, because there is rarely a map of where each screenshot is used. Then someone has to create updated visuals: go to the correct views in our app, reproduce the particular state, capture replacement images, annotate them as needed, and then update every one of the image references in the Markdown.

Multiply that by hundreds of screenshots given the velocity with which our product (and anybody else’s, really) evolves every week.

Now, taking a screenshot isn’t the hard part. With a few lines of Playwright or Puppeteer, an engineer can launch a browser, open a screen, and save a PNG. For a handful of screenshots, that might be all you need.

But generating the first 20 screenshots and maintaining many hundreds of them over time are two different engineering problems. Suddenly you’re dealing with authentication, asynchronous rendering, flaky selectors, dynamic data, multiple viewport sizes, annotations, sensitive-information masking, and retries. Then there’s what a script doesn’t handle: knowing which articles use an image, noticing when it goes stale, reviewing a visual change, and getting an approved replacement to production.

It’s easy for a modest browser automation script to grow into an internal platform that someone has to own and maintain. LaunchBrightly covers this in one of its articles, “Your Playwright script is the easy part.”

Capturing a screenshot is a task. Keeping screenshots accurate across our help articles is an ongoing workflow. And that’s the part we wanted to automate.

Our screenshot maintenance workflow is built around four steps:

  1. Reprocess: Generate consistent visuals from reusable browser automation recipes.
  2. Audit: Compare fresh captures with the screenshots in our documentation.
  3. Evaluate: Automatically approve routine changes and flag the rest for human review.
  4. Sync: Send approved updates through GitHub pull requests.

How the screenshot workflow is built

Step 1: Treat screenshots as reproducible assets

With LaunchBrightly, you store an image and the instructions for generating it.

Each managed screenshot has an automation recipe that describes how to move through our product, interact with the UI, and capture a particular state. For us, recipes will cover the main screenshot on each page of our product manual, and we’ll handle smaller views and close-ups another way.

A recipe will:

  1. Open up a custom browser in the required mode, say Desktop Light English
  2. Authenticate against our Tallyfy staging environment
  3. Go to the relevant product view
  4. Expand a sidebar, select a tab, or open a dialog and write some text or select an option
  5. Remove any unwanted elements, such as support bubbles or upgrade banners
  6. Capture the raw screenshot in full page mode or just as a smaller element depending on needs
  7. Apply any required annotations and styling
  8. Store the finished screenshot

Recipes are reusable, so they can be executed again and again on a recurring schedule as we need fresh visuals.

This is especially useful as we roll out major product updates. We won’t have to rebuild those main shots by hand, because we’ll be able to regenerate them at will.

LaunchBrightly also supports multiple capture modes, so the same recipe can produce variants for different screen sizes, device configurations, themes, or languages, which we haven’t used yet.

Step 2: Audit what the documentation shows

Generating fresh screenshots is only half the challenge. We also need to know whether the screenshots currently published in our documentation are different from the fresh visuals generated.

LaunchBrightly handles this through recurring visual help center audits.

On a schedule, it regenerates the managed screenshots, scans the documentation repository, finds the images referenced in the articles, and matches those images to the freshly generated versions. It then performs visual comparisons to identify discrepancies.

The process, somewhat naively, looks something like this:

  1. Scheduled audit
  2. Regenerate screenshots from automation recipes
  3. Scan documentation repository
  4. Match published images to fresh captures
  5. Compare visuals and identify changes
  6. Run Accept and Sync rules for automatic approvals
  7. Present audit results for human review, to accept and sync the remainder

Git on its own can only compare one version of a file with another. The audit compares what the documentation shows with what the product looks like on our staging environment. That lets it identify screenshots that are out of date, even when nobody has touched the documentation itself.

LaunchBrightly also identifies unmanaged visuals, which are images that exist in the documentation but don’t yet have an automation recipe.

When LaunchBrightly ran its first import of our product guide through the GitHub integration in October 2026, it identified 407 screenshots (340 unique) across 736 articles. Only 148 of those articles contained screenshots.

That gave us two useful things: an inventory of the visuals we already had and a clear opportunity to expand visual coverage as we continue improving the documentation.

Step 3: Sort routine changes from ones that need review

A visual difference isn’t necessarily a change that needs human review. But that doesn’t mean we shouldn’t update the screenshot!

In the past, keeping screenshots current with every small change in dates, counts and values would have been far too expensive. So we accepted that screenshots would gradually grow stale.

With LaunchBrightly’s Accept and Sync rules, we’ll be able to specify which changes we’re happy to approve automatically. Those can be dates and times, email addresses, currency values or phone numbers. When a new screenshot contains only changes covered by those rules, LaunchBrightly can approve it and send the fresh image to our documentation repo without anyone comparing the images first.

Changes that do deserve attention, like a rearranged navigation menu or a new option in a dropdown, will still come to us for review in a side-by-side comparison with the differences highlighted. The rules only decide whether a human needs to be involved.

And if a screenshot hasn’t changed at all, there’s nothing to sync. No unnecessary Git changes or CDN assets to fiddle with.

But even that tells us something. We’ll know the screenshot for that workflow is still up to date. It’s a bit like a unit test passing.

Step 4: Ship screenshots through GitHub

Tallyfy’s documentation lives in the tallyfy/documentation GitHub repository. We use an Astro/Starlight-based documentation pipeline, with our existing build and deployment process handling publication.

We didn’t want a separate process for images, so we’ve connected LaunchBrightly directly to that repository using its GitHub App. When screenshot changes are accepted, LaunchBrightly prepares the updated assets and the corresponding Markdown changes in a GitHub pull request.

For our setup, those fresh product screenshots (where changed) will be written to /screenshots/launchbrightly/. An article using those screenshots references them with ordinary Markdown:

![Task list showing due dates](/screenshots/launchbrightly/tasks/desktop-light-english-task-list.png)

When LaunchBrightly replaces a screenshot, it swaps only the image reference and leaves the rest of the article alone.

The pull requests target our staging branch and go through our existing documentation checks there. They only reach the live docs when we move changes from staging to production ourselves.

Our repository also has a few safeguards around that automation:

  • Every pull request from the LaunchBrightly GitHub App gets a check that fails if it changes anything besides screenshot files and the image lines of existing articles.
  • Our validation pipeline checks image naming, file types, sizes, and references.
  • LaunchBrightly doesn’t edit our asset inventory. If one of its commits ever did, our publishing step would refuse to run.
  • The downstream pipeline ingests the images into Cloudflare R2 and makes them available through our screenshot CDN. Nothing is deleted when a screenshot is replaced, so old image URLs keep working.

We keep the flexibility of our existing asset infrastructure, and LaunchBrightly will manage the lifecycle of those main shots.

And because updates move through Git, we get a familiar audit trail: changes are traceable, reviewable, and tied to the documentation files they affect.

LaunchBrightly batches approved screenshot changes into coordinated GitHub pull requests rather than opening one for every image. That matters because documentation updates can trigger downstream builds.

Under the hood: authentication and reproducibility

In the olden days, someone would sign into the Tallyfy app, go to the right view, get the UI looking just right (putting it into the correct state), and take a screenshot. Simple enough, but good luck reproducing that exact state six months later!

Our LaunchBrightly recipes will run against a demo organization on our staging environment, with a fresh browser session each run. That organization’s sample data resets every weekday, so the dates in it look current.

Our staging sign-in page sits behind Cloudflare Access, so the automated browser needs to get through that security layer, sign in to Tallyfy, and open the correct screen. All unattended, including during scheduled audits. LaunchBrightly supports two approaches: automating the normal login flow, just as a human would, and token-based authentication through HTTP headers, which lets the browser into protected environments without anyone signing in by hand.

That means every screenshot recipe can start from scratch, authenticate, and reproduce the same application state.

And consistency matters. We control screen dimensions, application data, navigation steps, and other variables that might otherwise introduce visual noise. If a screenshot changes because of a random data value or a different browser state, the audit becomes a lot less useful.

What this changes for our documentation team

Previously, a product UI change could quietly leave screenshots outdated until someone noticed, figured out how to recreate them, and manually replaced them.

Once the setup is running, LaunchBrightly will handle the whole cycle for the main screenshot on each page: regenerate screenshots, detect changes, match them to the right help articles, and send approved updates to our docs repo as pull requests. Nobody will have to chase down those shots when they go stale.

And we didn’t have to reinvent our engineering workflow. GitHub, Markdown, Astro/Starlight, and Cloudflare R2 are still doing their jobs.

But perhaps the biggest change is that we expect to add more screenshots without adding more maintenance work. Historically, every new screenshot came with an ongoing obligation to keep it current. Once the new audits are running, that obligation should get a lot lighter.

We use LaunchBrightly for automated product screenshots and visual audits in our documentation.

About the author

Amit is the CEO of Tallyfy. He has 20+ years of practical experience in technology, entrepreneurship, and operational efficiency. He's been hands-on with AI-first engineering and changing Tallyfy to AI-native workflow automation since Claude Code was first released. Before Tallyfy he spent years helping companies write down and improve how they work, and kept seeing the same problems: nobody read the documents, and nobody could see where any piece of work stood. He's also an Entrepreneur in Residence at WashU's Skandalaris Center, created the OneDay (Woolf) AI curriculum for their accredited MBA and consults with clients who need help with AI via Blue Sheen. He graduated with a Computer Science degree from the University of Bath. He's originally British and lives in St. Louis, MO.

Find Amit on his website , LinkedIn , or GitHub . Read Amit's bio →

Stop chasing people for updates

Tallyfy turns how your team works into simple steps, and shows you where everything stands.