A documentation screenshot should not be a loose image someone remembers to update before launch.
It should have a source route, a known state, a viewport, a wait condition, an owner, and a review step before it replaces the public docs asset. That is the difference between taking screenshots and operating screenshots.
Teams already know the pain. The product UI changes. The docs screenshot still shows the old nav. A modal moved. A settings page got renamed. A dark-mode screenshot came from the wrong account. Someone notices during release week, opens the product, creates a fake workspace, crops an image by hand, uploads it to the docs repo, and hopes no other screenshot is stale.
That workflow does not scale with a product that ships every week.
Automation starts with a scenario, not a screenshot
Browser automation can capture a page. That part is solved. Playwright's screenshot docs show the core primitives: page screenshots, full-page screenshots, element screenshots, buffers, clipping, quality, and format control. shot-scraper turns screenshots into a developer-friendly CLI workflow, and Simon Willison's launch post names one of the most practical uses: keeping screenshots in documentation up to date.
Those tools answer "can a browser capture this?"
Documentation teams need the next layer: "can we regenerate the right screenshot, in the right state, and know whether it is safe to publish?"
That starts with a scenario.
| Scenario field | Why it matters |
|---|---|
| Route | The product page, docs page, or local preview to capture |
| State | Signed-in user, plan, fixture data, language, theme, feature flags |
| Viewport | Desktop, mobile, retina, narrow panel, docs embed size |
| Ready condition | The selector, network state, or app signal that proves the UI is ready |
| Capture target | Full page, component, locator, or clipped region |
| Output path | Where the generated asset lands |
| Owner | Who approves replacement in docs |
A screenshot without a scenario is a file. A screenshot with a scenario is an artifact that can be rebuilt.
Pick one screenshot users depend on
Do not start by automating every image in the docs. That usually creates a brittle pile of scripts and fixtures nobody wants to maintain.
Start with one screenshot that creates support burden when it goes stale:
- API key creation
- billing settings
- OAuth connection
- workspace onboarding
- integration setup
- permission management
- dashboard empty state
- export configuration
The first scenario should be plain. Open the route. Load deterministic data. Wait for the ready element. Capture the region. Upload the artifact. Ask for review if the output changed.
That is enough to prove whether the workflow belongs in your docs pipeline.
The capture job is not the publishing job
CI can generate screenshots quickly. Publishing should be slower.
A generated screenshot can be wrong for many reasons. The fixture did not load. The user was not signed in. The app showed a cookie banner. The route was half-hydrated. The local server was on the wrong build. A feature flag changed the UI. A loading skeleton got captured. The browser viewport did not match the docs layout.
Automatically publishing that image is worse than leaving a stale screenshot for a day, because now the docs have a fresh-looking lie.
A safer workflow separates capture from approval:
- Detect a docs, UI, or scenario change.
- Run the screenshot scenarios in CI.
- Store generated artifacts with the build.
- Compare against the current docs asset.
- Mark changed screenshots for review.
- Publish only after approval.
GitHub Actions is enough to run this kind of workflow. The missing piece is usually not CI. It is the review object that tells the team what changed and whether the screenshot can replace the docs image.
Screenshots fail when product state is implicit
Most screenshot automation breaks because state is hidden in a human's head.
A person knows which account to use. A script does not. A person knows to dismiss the upgrade modal. A script does not. A person knows the screenshot should show the billing page after a card is attached. A script does not unless the scenario says so.
Make state explicit:
| Hidden assumption | Scenario version |
|---|---|
| "Use the demo workspace" | workspace fixture: demo-docs-workspace |
| "Make sure billing is active" | plan: team, payment_status: active |
| "Show the integration connected" | integration: github_connected |
| "Use the new nav" | feature flag: nav_2026_on |
| "Crop the settings panel" | capture target: locator('[data-docs-shot="settings-panel"]') |
The goal is not perfect determinism on day one. The goal is to remove enough ambiguity that the screenshot can run again next week.
Good documentation screenshots need reviewable diffs
Pixel diffing is useful, but docs screenshots are not visual regression tests in the strict sense. A changed screenshot is not automatically a failure. It may be the point of the product change.
The review question is different:
- Did the scenario capture the intended state?
- Does the screenshot still teach the step in the docs?
- Did the crop, viewport, or density change accidentally?
- Is the new UI public and ready to document?
- Should the docs text change with the image?
This is why Reshot treats the screenshot as a docs artifact, not just a test output. The artifact needs enough context for a writer, product marketer, engineer, or support lead to approve it without rerunning the whole product in their head.
The scenario file becomes the source of truth
A strong docs screenshot system eventually looks like this:
| Layer | Responsibility |
|---|---|
| Scenario manifest | Defines route, state, viewport, wait condition, and capture target |
| Browser runner | Uses Playwright or another browser engine to capture the asset |
| CI workflow | Runs scenarios on relevant changes and stores artifacts |
| Review queue | Shows changed assets with scenario metadata |
| Docs repository | Receives approved screenshots only |
That architecture is simple on purpose. It lets teams keep Playwright, GitHub Actions, Docusaurus, VitePress, Mintlify, MkDocs, or a custom docs stack. The screenshot workflow sits beside the docs, not inside every writer's muscle memory.
Use Reshot for the reviewable artifact
Reshot turns documentation screenshots into rebuildable, reviewable assets. Playwright can still capture the browser. GitHub Actions can still run the job. Your docs platform can still publish the final image.
Reshot keeps the scenario, generated artifact, review state, and approved output together.
That matters because documentation screenshots fail in the handoff. Engineers can write capture scripts. Writers can spot stale screenshots. Support can tell which steps confuse users. But without a shared artifact, every screenshot update becomes a one-off task.
The practical standard is simple: if a screenshot teaches a product step, it deserves a scenario. If a scenario changes, the screenshot deserves a review. If the screenshot passes review, it becomes the docs asset.
A screenshot is no longer a file someone drags into the repo. It is a build artifact with a reason to exist.
Decide what should never be automated
Not every image in documentation deserves a scenario. Some screenshots are better treated as editorial assets, especially when they are composed, annotated, or designed for a launch narrative rather than a repeatable product state.
Automate the images that teach stable product behavior. Be more careful with images that depend on taste, timing, or campaign context.
| Image type | Automation fit |
|---|---|
| Setup step screenshot | Strong fit |
| Settings page state | Strong fit |
| Integration connected or disconnected state | Strong fit |
| Dashboard with seeded data | Good fit if fixture is stable |
| Launch marketing collage | Weak fit |
| Annotated editorial image | Review manually or generate from a controlled source |
| Customer-specific example | Avoid unless anonymized and approved |
This keeps the system from becoming heavy. The goal is not to automate every visual. The goal is to remove manual drift from the screenshots users rely on to complete work.
Keep docs text and screenshots in the same review
A screenshot change often means the text around it needs to change. A button label changes from Create key to Generate key. A setup page moves from Settings to Integrations. A modal becomes a side panel. If the image updates but the instructions do not, the docs still feel stale.
The review should show the docs page where the screenshot appears. That lets the reviewer ask the right question: does this image still support the surrounding instruction?
A strong review packet includes:
- old screenshot
- generated screenshot
- scenario metadata
- docs page path
- nearby heading or step text
- product route
- reviewer decision
That is the difference between image replacement and documentation maintenance. Reshot belongs in that maintenance loop.
Sources
- [C1] Playwright screenshots - Official documentation for page, full-page, buffer, and element screenshots.
- [C2] shot-scraper docs - CLI documentation for automated website screenshots.
- [C3] shot-scraper launch post - First-party explanation of screenshot automation for documentation use cases.
- [C4] GitHub Actions docs - CI workflow and artifact automation reference.
Top comments (0)