Your Docs Show a Button That Doesn't Exist Anymore

I was onboarding onto a new project last month. The docs said "Click the Export button in the top-right corner." There was a screenshot showing a blue "Export" button next to a search bar.

I stared at the UI for two minutes. There was no Export button. There was no search bar either. The entire top bar had been redesigned 4 months ago. Nobody updated the screenshot.

I figured it out eventually by poking around. But I shouldn't have had to.

This happens everywhere

Look at any documentation site for a product that ships weekly. At least a third of the screenshots will be outdated. Not slightly outdated. Completely different UI.

Why? Because updating screenshots is painful:

1. Open the page
2. Log in (if it's behind auth)
3. Navigate to the right state
4. Resize the browser
5. Find the element
6. Take the screenshot
7. Crop it
8. Name it correctly
9. Replace the old file
10. Commit and push

Do that for 30 screenshots and it's a full afternoon. Nobody voluntarily does that.

Make it one command

Define your screenshots in config once:

{
  "screenshots": [
    {
      "name": "export-button",
      "url": "https://app.example.com/dashboard",
      "selector": ".toolbar .export-btn",
      "padding": { "top": 8, "right": 8, "bottom": 8, "left": 8 }
    }
  ]
}

Update all of them:

npx heroshot

That's it. Every screenshot regenerates from the live UI. If the Export button moved, the screenshot shows where it actually is now.

Don't write JSON by hand

The visual picker does it for you:

npx heroshot config

Navigate to your app in the browser. Click the element you want to capture. Move on to the next page. Click another element. When you're done, close the browser. Config is written.

Put it in CI

# On every deploy
- name: Update doc screenshots
  run: npx heroshot

Now screenshots update automatically when the UI changes. The docs never show a button that doesnt exist anymore.

Heroshot is free and open source. But even if you use something else, please automate your screenshots. Your users are staring at the screen wondering where that button went.