A screenshot sweep feels productive until it becomes the release ritual everyone dreads.
Someone opens every docs page. Someone compares the current UI with screenshots from three months ago. Someone asks which workspace has the right data. Someone retakes a settings page. Someone crops it differently than last time. Someone notices the nav changed in another article. Launch week turns into a scavenger hunt for stale images.
The problem is not that teams forget screenshots. The problem is that screenshots are not connected to the product changes that make them stale.
Stale screenshots are visual debt
Visual debt accumulates whenever a product image no longer matches the current product experience. It is quiet at first. One button label changes. A sidebar moves. An empty state gets redesigned. A plan name changes. The docs still mostly work, so nobody stops the release.
Then support tickets get slower because users do not see what the docs show. Sales engineers stop trusting setup guides. Product marketing avoids screenshots because they might be wrong. Writers spend launch week auditing images instead of improving the page.
The debt exists because a screenshot usually has no owner, no scenario, and no trigger.
| Screenshot problem | Operational cause |
|---|---|
| Old UI appears in docs | No link between UI change and docs asset |
| Wrong account state | Fixture is implicit or manually recreated |
| Inconsistent crop | Capture target is not defined |
| Stale mobile image | Viewport was not part of the scenario |
| Broken screenshot in release week | Review happens after the product ships |
The fix is not a heroic sweep. The fix is to turn important screenshots into maintained scenarios.
A screenshot needs a trigger
A docs screenshot should regenerate when the product area it represents changes. That does not mean every commit should rebuild every screenshot. It means each scenario should know what it depends on.
A setup screenshot might depend on the integration settings page, the connected-state fixture, and the docs file where the image appears. A billing screenshot might depend on the billing route, plan fixtures, and the page that explains invoices. A dashboard screenshot might depend on a demo workspace fixture and a set of chart components.
When one of those inputs changes, the screenshot becomes suspect.
A useful trigger model is simple:
| Change detected | Screenshot action |
|---|---|
| Docs page changed but product route did not | Rebuild linked screenshots for review |
| Product route changed but docs page did not | Rebuild affected screenshots and flag docs owners |
| Fixture changed | Rebuild scenarios using that fixture |
| Viewport or capture target changed | Require review before publishing |
| Only unrelated code changed | Skip screenshot run |
This keeps automation focused. The team reviews screenshots when the product or docs created a reason to review them.
Use browser automation for capture, not judgment
Tools like Playwright are excellent at capturing pages, full pages, and locators. shot-scraper is useful when a team wants a CLI-first screenshot workflow. GitHub Actions can run the capture job in CI and store artifacts.
Those pieces handle capture and execution. They do not decide whether an image still teaches the right thing.
That decision belongs to review:
- Is the new UI the public experience?
- Does the screenshot match the step in the docs?
- Did the automation capture a loading state?
- Did a banner, modal, or test account artifact appear?
- Does the docs copy need to change with the image?
A changed screenshot is not always bad. Sometimes the product changed correctly. The review exists so the right image publishes with the right explanation.
The scenario is the maintenance contract
A scenario is a small contract between the product and the docs.
It says: to produce this image, open this route, set this state, use this viewport, wait for this element, capture this target, and ask this owner before publishing changes.
That contract removes the guesswork from screenshot maintenance.
| Scenario field | Example |
|---|---|
| Docs page | docs\/integrations\/github.mdx |
| Product route | \/settings\/integrations\/github |
| Fixture | workspace with GitHub connected |
| Viewport | 1440x900 desktop |
| Wait condition | data-docs-ready="github-connected" |
| Capture target | integration settings panel |
| Owner | docs-platform |
The scenario does not need to be elaborate. It needs to be explicit enough that the screenshot can be regenerated without asking a teammate which account they used last time.
Build a review lane, not a screenshot dump
The common failure mode is a CI job that drops a folder of PNGs somewhere. That is better than manual capture, but it still asks humans to infer what changed.
A review lane should show the scenario metadata with the image:
- screenshot name
- docs page where it appears
- product route captured
- fixture and viewport
- old asset and new asset
- changed reason
- reviewer decision
The reviewer should be able to approve, reject, or request a scenario fix. Rejection matters. Sometimes the screenshot is stale because the docs need updating. Sometimes it is wrong because the scenario captured the wrong state. Sometimes the product changed and the docs asset should not publish until the release is public.
Keep the publishing path conservative
Fast generation is good. Conservative publishing is better.
Do not let screenshot automation silently replace public docs assets unless the screenshot category is truly low risk. For product setup flows, billing pages, security settings, admin permissions, and integration states, review should be required.
A practical policy:
| Screenshot type | Publish policy |
|---|---|
| Decorative marketing image | Manual review |
| Product setup step | Required review |
| Security or admin setting | Required review |
| Generated reference image | Review unless scenario is stable and low risk |
| Test-only internal screenshot | Auto-upload as artifact, never publish |
This policy keeps automation from becoming a source of polished mistakes.
Use Reshot to remove the sweep
Reshot is built for the job between browser capture and docs publishing. It keeps scenarios, generated screenshots, review status, and approved assets together.
The workflow becomes predictable:
- A product or docs change touches a scenario input.
- CI runs the relevant screenshot scenarios.
- Reshot stores the generated artifacts with scenario context.
- Reviewers approve the screenshots that still teach the right thing.
- Approved assets replace the docs images.
That is how teams stop doing launch-week screenshot sweeps. They still review screenshots, but they review the ones that changed for a reason, with enough context to make a decision.
The goal is not to eliminate human taste from documentation. The goal is to stop using human memory as the screenshot system.
Do one inventory, then stop doing sweeps
There is still value in one manual inventory. The point is to make it the last broad sweep, not the new habit.
Start by listing every screenshot in the docs and assigning it a maintenance status:
| Status | Meaning |
|---|---|
| Scenario candidate | Product state is repeatable and useful to automate |
| Editorial asset | Keep manual, usually launch or narrative imagery |
| Remove | Screenshot no longer teaches enough to justify maintenance |
| Replace with text | The step is clearer without an image |
| Needs product fixture | Valuable, but state is not deterministic yet |
This inventory usually reveals that fewer screenshots deserve automation than expected. Some images can be deleted. Some can become text. Some need better product fixtures before capture makes sense. The remaining set becomes the scenario backlog.
After that, stop sweeping the whole docs set before each launch. Review only screenshots connected to changed docs, changed product routes, changed fixtures, or changed scenarios.
Make screenshot ownership boring
A screenshot without an owner becomes everyone's problem and nobody's responsibility.
Ownership does not need to be complicated. Each scenario needs one accountable group: docs platform, product marketing, developer relations, support, product team, or sales engineering. The owner does not have to take every screenshot manually. They decide whether a generated change can publish.
Good ownership answers three questions:
- Who reviews changes to this screenshot?
- Who fixes the scenario when capture breaks?
- Who updates the docs text if the UI changed?
When those answers are visible, stale screenshots stop being surprise work during launch week. They become small review tasks attached to the product changes that created them.
Sources
- [C1] Playwright screenshots - Browser screenshot primitives for pages, full pages, and elements.
- [C2] shot-scraper docs - CLI workflow for automated website screenshots.
- [C3] GitHub Actions docs - CI workflows and artifact handling.
Top comments (0)