Skip to content

Keep documentation screenshots up to date

The Docs Agent can recapture stale documentation screenshots from your live product. First, run a one-off refresh yourself to confirm the agent captures your product correctly. Then, use an automation to keep the images current.

You need:

  • Automations and the Sandbox tab turned on for your organization. If you don’t see Automations in the sidebar, or Sandbox under Settings > Docs Agent, contact support@ekline.io.
  • A repository connected to EkLine that holds both your documentation pages and their image files.
  • A sandbox for each product URL your screenshots come from. The sandbox gives the agent the address to visit and, for pages behind a login, the sign-in variables it needs.
  • Documentation pages that reference their screenshots. The agent finds candidate images by reading how your pages reference them.

Step 1: Confirm the sandbox reaches your product

Section titled “Step 1: Confirm the sandbox reaches your product”

The agent can only recapture a screen it can open. Verify this before you schedule anything.

  1. Go to your EkLine dashboard and open Settings > Docs Agent > Sandbox.

  2. Confirm a sandbox appears under Configured sandboxes with the URL your screenshots come from. Note its name: you need the name, not the URL, in Step 3.

  3. If no sandbox matches, create one.

Run one refresh yourself before you put it on a schedule. You see what the agent captures, and you find any sign-in or navigation problem while someone is watching.

  1. Open the Docs Agent editor and start a new session.

  2. Ask the agent to refresh your screenshots against the sandbox by name:

    Check the screenshots in our documentation against the
    staging-admin sandbox. Recapture any that no longer match
    the product, then open a pull request.
  3. Watch the Live browser panel as the agent signs in and navigates. Each page it opens appears in real time.

  4. Review what the agent reports. It lists the images it recaptured, the screen each one depicts, and any image it deferred with the reason.

  5. Click Raise PR to open a pull request with the new images. The button prefills a chat message. Send it, and the agent opens the PR.

With the sandbox proven, hand the recurring work to an automation.

  1. Click Automations in the sidebar.

  2. Find Doc Screenshot Refresh under the Accuracy tab, or enter its name in Search, then click Set up on its card.

  3. In Sandbox name(s) to screenshot against (one per line), enter your sandbox name, for example staging-admin. The field starts empty, and the automation cannot turn on until you fill it in.

  4. Under Schedule, the default is every week on Monday at 9:00 AM. Monthly suits most teams, because screenshots drift more slowly than prose and each run changes at most five images: set Repeat every to 1 month and select a day under Repeat on. Keep weekly if your interface is under active redesign.

  5. Under Notifications, leave Raise a pull request checked, so the agent delivers each run’s images in a pull request for review.

  6. Send a Slack notification is also checked. Enter a channel name, such as docs-team, and the agent posts a summary of each run there. Or clear the checkbox.

  7. Click Turn on.

What the agent changes and what it leaves alone

Section titled “What the agent changes and what it leaves alone”
The agentDetail
Recaptures product screenshotsImages that show your product’s interface, cropped to the element the image depicts
Creates missing imagesWhen a page’s prose and alt text call for a screenshot that isn’t there
Replaces only structural changesA renamed label, a moved control, a new field or a reworked layout: a change a reader would act on
Skips dynamic contentRow values, timestamps, chart figures, and the signed-in username differ on every visit, so the agent leaves those images alone rather than churning your docs each run
Skips non-screenshotsDiagrams, logos, illustrations, and mockups stay untouched
Caps each runAt most five images per run, missing images first. It reports anything it defers
Changes images, not proseFor documentation that describes the interface incorrectly in text, use the Doc UI Accuracy Review template instead

Confirm both stages are in place:

  • A sandbox for each product URL appears under Configured sandboxes in Settings > Docs Agent > Sandbox.
  • The Doc Screenshot Refresh card on the Automations page has its toggle on.

To see the output before the first scheduled run, click Edit on its card, open the Runs tab and click Run now. Then, under Recent runs, click the run’s start time to open the full session.

IssueSolution
The run reports that it couldn’t sign inThe sandbox variables are wrong, or the sign-in form needs a value the sandbox doesn’t have. See The agent can’t sign in.
The agent browsed the site but stayed signed outThe page host doesn’t match the sandbox URL. A sandbox for staging.example.com doesn’t apply to app.example.com.
The run finished without a pull requestNothing needed replacing. When every candidate image differs only in dynamic content, the agent discards the captures rather than opening an empty pull request.
A screenshot you expected wasn’t updatedCheck the run’s deferred list. Common reasons: the agent couldn’t tell which screen the image shows, the image isn’t a product screenshot, or the run hit its five-image cap.
The run defers images because a sandbox is not configuredThe sandbox name you gave doesn’t match a configured sandbox. Names are fixed at creation, so confirm the exact spelling under Configured sandboxes.
Recaptured images show test data you don’t want publishedPoint the sandbox at an account with presentable data, then re-run. Review each image in the pull request before merging.

Built on Potluck Docs, our open source template.