Images
Add a screenshot only when it earns its place, keep sensitive data out of it, and give every image its alt text.
Use a screenshot only when words failed
Every screenshot is a maintenance cost. The interface changes without notice, the page goes stale silently, and a stale screenshot misleads with full confidence. Add one only when the words alone did not carry the instruction.
The test: if the sentence names the control and the action clearly, the screenshot repeats it. Delete the screenshot, keep the sentence.
Keep sensitive information out
A screenshot never shows real account data: names, e-mails, tokens, domains, or identifiers. Capture a test account, or mask the values before publishing. A leaked value in an image is as public as a leaked value in text, and harder to find later.
Crop to the relevant area
Capture the part of the interface the instruction points at, not the full screen. Volatile interface chrome — menus, avatars, version banners — dates the image and distracts from the control that matters.
Write alt text for every image
Alt text states what the image conveys, in one sentence. The rules are in Accessibility.
Format the asset path
Asset paths are root-absolute with no language prefix, because one image serves both language versions:
- Correct:
/assets/docs/images/uploads/diagram.png
Historical records are exempt
Screenshots in changelogs and release notes record what the interface looked like at that date. They are point-in-time records: do not update them when the interface changes.