Every Screenshot in Your Documentation Has an Expiry Date

There is a tip sheet on my desk from a previous engagement that shows a toolbar with eleven icons. The current version of that application has nine. Two of the eleven were consolidated into a menu in an upgrade three years ago, and one moved to the other side of the screen. The tip sheet is otherwise perfect. The steps are right, the sequence is right, the warning in the middle about the thing that will silently fail is right and is not documented anywhere else.

Nobody can follow it, because step two says click the icon that is third from the left, and the icon that is third from the left now does something different.

This is the most common way documentation dies in a hospital, and it is almost always self-inflicted by someone trying to be helpful.

Why authors reach for screenshots

I want to give the instinct its due, because the people doing this are not being lazy. Quite the opposite — pasting a screenshot into a document takes more effort than writing a sentence, and they are doing it out of care.

The reason is that a screenshot feels like proof. When you are writing instructions for something you understand well, the hardest part is imagining what a person who does not understand it will find confusing. A screenshot lets you skip that imaginative work. You do not have to figure out what to call the button, or whether the panel is a panel or a pane or a sidebar, or whether the reader will know what you mean by the workspace. You just show them.

That feeling of certainty is exactly the problem. The screenshot has not removed the ambiguity, it has deferred it — to a reader who is looking at a screen that no longer matches, and who now has to work out whether the difference is because they are in the wrong place or because the picture is old. That is a worse position than being given a vague instruction, because a vague instruction prompts them to look around, while a confidently wrong picture prompts them to conclude they are lost.

Rot rates are not uniform

The useful frame is not "screenshots go stale." It is that different parts of a document decay at very different rates, and screenshots sit at the fast end of a range most people have never thought about explicitly.

At the slow end is clinical reasoning — why a protocol exists, what it is protecting against, what to consider before deviating. That content can sit unchanged for years and stay correct.

In the middle is process: who approves this, where it goes next, what the escalation path is. That changes at the pace of reorganizations, which in most health systems means every couple of years, unpredictably.

At the fast end is anything that describes a user interface. Vendor upgrades come on the vendor's schedule, not yours. A quarterly release train means a document with screenshots has a shelf life measured in months, and nothing in your review calendar knows that. Your policy review cycle is annual because policy review cycles are annual everywhere, and it is applying a one-year interval to content with a three-month half-life.

Contact lists sit right there too, and everybody knows it, which is why the phone list is the one document people distrust by default. The interesting thing is that people do not extend that same distrust to click paths, even though click paths change more often than phone numbers.

Write steps that survive the redesign

Most of the fix is a writing habit rather than a policy.

Name things by their label, not their position. "Select Orders" survives a layout change. "Click the third tab" does not. If the label is genuinely ambiguous, say where it is as a hint after the label, not instead of it.

Describe the goal alongside the mechanism. A step that reads "open the flowsheet where vitals are entered — from the chart, choose Flowsheets" gives the reader something to fall back on when the second half stops matching. A step that reads only "choose Flowsheets" leaves them with nothing.

Avoid documenting the parts of the interface that are decoration. If your instructions mention a colour, an icon shape, or the number of items in a list, you have coupled your document to something the vendor changes casually.

And keep the numbers out of the prose where you can. "Fill in the required fields" ages better than an enumeration of which fields are required, because required-field configuration is exactly the sort of thing a build analyst adjusts on a Tuesday without telling anyone.

When a screenshot is worth its maintenance cost

I am not arguing for never. There are cases where a picture is doing work no sentence can do, and refusing to use one out of principle is its own kind of failure.

The test I use is whether the reader would otherwise be unable to identify the thing. If two screens look nearly identical and the only way to tell them apart is a visual detail, show the detail. If the hard part of the task is recognising a state — a status indicator that means the order did not transmit, a subtle difference between two similar dialogs — a picture earns its keep, because you are documenting recognition rather than navigation.

When you do use one, crop it hard. A screenshot of one control with a bit of surrounding context survives changes to the rest of the screen. A full-screen capture is guaranteed to be invalidated by any change anywhere in the application, including changes irrelevant to your instructions.

And record what it is a picture of. A caption naming the application and the version it was captured from turns a silent expiry into a visible one — the next reader can see at a glance that the picture predates the upgrade, instead of concluding they are in the wrong place.

Find them before the upgrade does

The practical exercise, and it is one you can run in an afternoon before your next release, is to find every document that contains an image and sort it by which application it depicts. Most organizations cannot do this, which is itself informative — the images are embedded in files scattered across the locations described in every other article on this blog, and there is no inventory.

If you can only do one thing, do this one: before an upgrade, get the release notes, pull the list of screens that changed, and search your documentation for the words on those screens. Not the screenshots — the words. Then triage. You will not have time to fix everything, and you should not pretend otherwise. Fix the documents that get opened most, retire the ones nothing has touched in two years, and put a visible note on the rest saying which release they were written against.

This is also where a retrieval layer changes the calculus, and it is why Solution Compass surfaces how often each source actually gets returned. The question "which of these three hundred tip sheets is worth re-capturing" is unanswerable by inspection and trivial once you know which ones people are actually landing on.

The tip sheet on my desk gets opened, by the way. Somebody in that organization still sends it to new hires. They have learned to say, in the email, that the icons have moved since — passing along a correction verbally, one person at a time, exactly the way we did before anyone wrote anything down.