Every screenshot in your docs is a promise to update it when the UI changes. Most teams don't keep that promise.
I've audited enough documentation sites to say this plainly: screenshots in documentation are the worst cost-per-maintenance ratio of any content you can ship. They look helpful in the PR. They feel complete on the page. Six months later they're lying to your users, and nobody notices until a support ticket mentions a button that no longer exists.
The honest version of a screenshot-heavy doc is: "This was true the day we published it." You don't get credit for a screenshot the moment the UI drifts. You get blame.
The four quiet failures
Walk through any mature docs site and you'll find the same four failure modes on the screenshots.
UI drift. The button moved. The sidebar got a new item. The modal was redesigned. Your screenshot still shows the old one, and the user is now comparing two different products side by side, trying to figure out which one is real.
Dark mode mismatch. Half your users are in dark mode. Your screenshots are from whoever wrote the doc, which means they're usually light mode. Now the page shows a light card embedded in a dark article, and the visual break trains the reader to distrust the image.
Locale drift. You shipped a screenshot with English labels. A French user lands on the localized doc, sees "Save Changes" in the image and "Enregistrer les modifications" in their UI, and has to mentally translate in real time. Or worse, you shipped localized screenshots and now you have ten versions to maintain when the button renames.
Rename regret. The feature was called "Projects" on launch day. It's called "Workspaces" now. Every screenshot with the old label is a tiny landmine. You'll catch maybe 40% of them on the rename PR. The rest stay wrong for years.
Contrast this with text. A code block showing docsio publish --env prod survives a sidebar redesign, a dark mode launch, a Portuguese translation, and three button renames without a single edit. A JSON response body doesn't care what your login screen looks like. CLI output, API examples, curl commands, and config files are effectively free to maintain. They're not "as good" as screenshots. They're strictly better on the dimension that matters after week one: staying correct.
The strongest counter-argument
Some workflows genuinely need screenshots, and I'm not going to pretend otherwise.
If your product is a visual canvas (Figma, a whiteboard, a node editor), you can't explain drag-and-drop with a code block. If the doc is teaching someone to spot a specific UI pattern ("the red warning banner at the top of the billing page"), the image is the content. If you're writing onboarding for non-technical users who bounced off a text-only walkthrough, a screenshot of the exact "Create Project" button they're looking for does more work than three paragraphs describing where to click.
The test I use: would a blind user following a screen reader be able to complete the task? If yes, the screenshot is decoration and you're paying the maintenance tax for nothing. If no, you probably need the image, and the job is making it the cheapest possible version of itself.
That's the real question. Not "screenshots or no screenshots." It's "given that this screenshot has a maintenance cost, is the user outcome worth it?" For most settings panels, dashboard tours, and feature walkthroughs, the honest answer is no. For the three screens where the visual IS the instruction, the answer is yes.
What I'd do instead
Keep a short list of rules that let screenshots earn their slot.
- Link to the live thing whenever possible. Instead of showing the settings page, link to the settings page. If the user is logged in, they land on the real UI, which is by definition current. Doc rot can't happen on a URL.
- Use annotated SVGs for layout explanations, not pixel-perfect mocks. A simple wireframe with arrows labeling regions ("nav here, content here, footer here") survives every UI redesign. It's also smaller, accessible to screen readers if you label the nodes, and loads faster.
- Replace "how to click through" with CLI or API equivalents. If your product has an API, showing the
POST /projectscall is more useful than eight screenshots of the project creation wizard. Engineers prefer it, and the docs don't break when you redesign the wizard. - For workflows that truly need video, record Loom with timestamps. A 45-second Loom with "0:12 click settings, 0:18 paste the key" captions holds up better than 12 static screenshots of the same flow. It also degrades visibly when out of date (the UI in the video looks old), which is a feature, not a bug. Users spot the rot before you do.
- When you do embed a static screenshot, log the feature version next to it. Literally: caption "Dashboard as of v4.2." That single line tells future-you and future-users when to distrust the image, and it makes the update cost visible in the source file.
None of this is new. What's new is being willing to say "this screenshot isn't worth keeping" and cut it, which most teams treat as admitting defeat. It isn't. A doc with fewer, load-bearing images beats a doc with 40 drifting ones, every time.
The meta point
Docs are a codebase. You wouldn't ship 40 hardcoded strings into your product and say "we'll update these by hand when anything changes." You'd parameterize. Documentation deserves the same instinct. Text and code references parameterize themselves against UI change. Screenshots don't.
The documentation workflow question most teams skip is "what's our update budget?" If the answer is "a few hours a quarter," you can't afford screenshot-heavy docs and you need to write that into your style guide now, not after the first redesign. Same principle applies to versioning: every screenshot multiplied across three versions is three times the rot surface area.
Sometimes the reason users don't read your docs isn't length or tone. It's that they stopped trusting the screenshots six months ago, and the trust didn't come back.
So the question I'd leave with anyone refactoring a docs site: if you removed every screenshot that isn't strictly load-bearing, what would break? If the answer is "nothing," you've just found the cheapest doc quality improvement of the year.