A help article with an old screenshot is worse than no screenshot: the reader looks for a button that has moved, decides the product is broken, and calls support. DentX ships changes most days, and its screenshots appear in five places: the help centre, a printed user guide, marketing feature pages, explainer videos, and the super-admin guide. This is how we went from four separate screenshot scripts to one catalog that knows which pictures a code change has made stale.
TL;DR
- Every product screen used anywhere is one entry in one catalog. Each consumer keeps its own names as aliases, so nothing downstream had to be renamed.
- One capture engine renders each entry once per language at print resolution and stores it as a master. A publish step derives every consumer's files from the masters.
- While a screenshot is taken, the server records which templates it rendered. Later, any newer template, stylesheet, script or translation file marks that screenshot as stale.
- After a UI change, one command recaptures exactly the stale pictures and republishes them.
- The honest limit: a change to a partial used on every page makes every picture stale. Today that is all 843.
The problem: five copies of the same screen
Before the catalog, each consumer had its own capture script. The printed guide had one, the help centre had a flag on that script, the feature pages had their own builder, and the super-admin guide had a fourth. They logged in with different demo users, used different window sizes, and hid different things. The same screen could exist in four versions taken weeks apart. When the owner changed the app's contact number, the old number lived on in pictures nobody remembered to retake.
Product rules made it harder. Our pictures must never show demo-account badges, and outside the subscription screens they must never show the words "free" or "subscription", because the mobile apps cannot mention pricing. Each script implemented those rules a little differently.
Why the usual fixes fall short
Retake everything on a schedule. A full run of both languages is long and loads the machine; doing it nightly for a few changed screens wastes most of the run, and a weekly run still leaves days of wrong pictures.
Retake by hand when you remember. This is what we had. It fails silently: nobody notices an outdated picture until a customer does.
Visual diffing against production. Comparing new captures with old ones tells you what changed only after you have recaptured everything, which is the expensive part.
The fix, in four parts
1. One catalog with aliases
Each entry describes how to take one picture: the demo user, phone (390×844 at 3×) or desktop (1440×900 at 2×), the address, where to scroll, what to hide, optional scripted steps, and numbered callouts for the printed guide. The entries come from five part-files, one per consumer, so each team-facing list stays readable. When two entries would produce exactly the same picture (same user, size, address, scroll and styles, with no scripted steps), the second becomes an alias of the first and the screen is captured once.
guide:c3-feed → c3-feed
help:cases-feed-desktop → help-cases-feed-desktop
feat:dental-store/hero@desk → feat-dental-store-hero-desktop
sa:map → sa-map
Today the catalog resolves 1,810 names to 843 masters: 445 phone and 398 desktop. 33 masters are used by more than one consumer.
2. One engine, one scrub
The engine starts the app on a local port with demo data in the target language, opens Chrome with the production hostname mapped to the local server (so the Google Maps key, which is restricted to our domain, still works), and takes each shot. Before anything is rendered it installs one scrub: it hides demo badges and sponsored placeholders and rewrites the handful of pricing phrases the apps must not show. Subscription and payment screens get a lighter scrub, and the super-admin guide gets none.
After the shot, the engine also audits the page text and records flags: demo wording that slipped through, pricing words, the retired contact number, the old sidebar, the retired seven-tab clinic settings screen, and a map that fell back to OpenStreetMap. The audit reports; it does not block. In the latest Arabic run it flagged 10 masters still showing the retired settings tabs and 11 outside the admin area with demo wording, which tells us exactly where to look. Most of its 29 "old sidebar" flags are the admin screens, which legitimately keep a sidebar, so we read the flags rather than fail the run on them.
3. Masters, then publish
Masters are full-resolution PNGs, large enough for 300-dpi print: 1170×2532 for phone and 2880×1800 for desktop. They are not committed to git; the Arabic and English sets together take 740 MB. A publish step derives the consumers' files: WebP for the help centre (780 px phone, 1440 px desktop) and for the feature pages (two widths per device), clean and callout copies plus print and screen JPEGs for the printed guide, and JPEGs for the admin guide. Videos and flyers read the masters directly. Publish only rewrites a file whose master is newer.
4. Knowing what is stale
This is the part that removed the guesswork. The capture server is started with a small preload that wraps the template engine's compile function and appends every template file it compiles to a trace log, with a timestamp:
const compile = ejs.compile;
ejs.compile = function (tpl, opts) {
if (opts && opts.filename) appendFileSync(TRACE, Date.now() + '\t' + rel(opts.filename) + '\n');
return compile.apply(this, arguments);
};
Each master's index entry keeps the templates rendered while it was taken, the stylesheets and scripts the page loaded, and a fingerprint of its own catalog entry, including the source of any scripted steps. A master is stale when it is missing, when its catalog entry changed, or when any of those files, or the translation files of its section, is newer than the capture. The check needs no browser and runs in seconds:
node docs/shots/capture.js --stale # list stale masters and why
node docs/shots/capture.js --stale --apply && node docs/shots/publish.js
What the help centre does with them
Help articles are Markdown files; a picture is written as . If a desktop twin of that picture exists, the figure carries both, shows the desktop image on wide screens and the phone image on narrow screens and inside the mobile app, and adds a "phone / computer" switch. The hidden image is lazy, so it is never downloaded. Each second-level heading in an article is one question with its own page, which is how 46 Arabic articles become 142 question pages. The Arabic help folder currently holds 367 pictures, 203 of them desktop.
Measured results and honest limits
- One source for every product picture, replacing four capture scripts that disagreed about users, sizes and scrubbing. The old commands still work and forward to the new engine.
- The English masters lag: 755 of 843 exist, against all 843 in Arabic, because the written help is Arabic-first for now.
- The limit we hit today: running the staleness check now reports all 843 Arabic masters as stale. 732 of them are stale because of one small partial that is included in every page's head; another 53 because of the menu translations, 26 because of the admin layout, and 25 because their catalog entries changed. The dependency tracking is correct, but it is file-level: it cannot tell that a change to an install-banner partial has no visible effect on a screenshot. We chose to keep it conservative. A full recapture costs machine time; a wrong picture costs a customer's trust.
Checklist
- Put every screenshot in one catalog, and let consumers keep their names as aliases.
- Capture at print resolution once and derive web sizes from that master.
- Apply content rules (no demo marks, no pricing words) in one scrub, and audit the rendered text after every shot.
- Record, per screenshot, what it depended on: templates, assets, translations, and its own spec.
- Make "what is stale?" a fast command that needs no browser.
- Expect shared partials to invalidate everything, and decide in advance whether that is acceptable.
Need this?
Our standing rule is that every GeoTech product ships with a help centre built this way: one question per page, real phone and computer screenshots, and a support-agent view with ready replies. If your documentation keeps falling behind your releases, talk to GeoTech.