Images and media

Images, screenshots, and video can significantly improve documentation — but only when they serve a purpose that text cannot serve as well. Used without discipline, visual content clutters documentation, slows page load, becomes outdated quickly, and creates accessibility problems. This article covers when to use visual content, how to use it well, and what to do when you do. It is the authoritative source for alt text and media file naming conventions; other articles referencing these should point here.

When to Use Images

Use an image when it communicates something that text would communicate less clearly or more slowly. The standard is not "this would look nice" — it is "a reader who sees this image will understand something they might not have from text alone."

Images add genuine value when:

• The UI has multiple possible paths and a screenshot confirms which one the reader is on.
• A spatial relationship needs to be shown (the location of a button in a complex interface).
• A concept is genuinely visual and a diagram would make it significantly clearer.
• The result of a step needs visual confirmation (what success looks like).

Images do not add value when:

• They simply show the UI element that the text already describes clearly.
• They decorate a page without contributing information.
• They will become outdated quickly as the UI evolves.
• The screenshot is of a simple, universally recognizable element (a standard text field, a generic dialog box).

Screenshot Guidelines

Capture only what is relevant

Crop screenshots to show only the relevant portion of the interface. A full-page screenshot of an entire admin panel, when only one panel or button is relevant, forces readers to hunt for the thing you are pointing to. Crop tightly, or use annotation to highlight the relevant element.

Annotating screenshots

When a screenshot needs annotation to draw attention to a specific element, use one consistent visual convention throughout the knowledge base:

• A single accent color, distinct from any color used elsewhere in the product UI, reserved only for documentation annotations.
• A consistent shape for pointing to an element — a rounded rectangle outline is a common, unobtrusive choice — rather than mixing arrows, circles, and boxes across different articles.
• Numbered annotations when a screenshot illustrates a multi-part interface (matching numbers to a short list below the image), rather than a wall of arrows and labels crowded onto the image itself.

Keep screenshots current

Screenshots are the fastest content to become outdated. An interface update that changes a button's label, position, or color makes a screenshot misleading. When you update an article, check whether screenshots are still accurate. If a screenshot cannot be kept current, consider whether text is more maintainable than an image for that piece of information.

Avoid screenshots of text-only content

A screenshot of a dialog box that just contains a message is worse than quoting the message in the text. Text in screenshots is not searchable, not copyable, and not accessible to screen readers. If the content is text, write it as text.

Localized screenshots

For a knowledge base published in multiple languages, decide this deliberately rather than by default: a screenshot showing the UI in English within an otherwise-translated article is confusing for a reader whose product interface is also localized. Where the product UI is available in the reader's language, localize the screenshot to match. Where a screenshot is expensive to localize and the UI element it shows is simple enough to describe in text instead, prefer text over an English-only screenshot in translated content.

Image dimensions and file size

Capture and export screenshots at a resolution appropriate for on-screen display — not raw, unscaled native resolution from a high-density display, which produces unnecessarily large files and slow page loads. Compress images before publishing, and keep an eye on total page weight for articles with many screenshots.

Consistent style

Screenshots within the same knowledge base should have a consistent visual style: same dimensions, same annotation conventions, same border treatment if used. Inconsistency in screenshot style makes the documentation feel piecemeal.

Diagrams and Illustrations

Diagrams are worth the investment when they explain a concept — a system architecture, a workflow, a data relationship — that would take many paragraphs of prose to approximate.

Keep diagrams simple. A diagram that requires a legend to understand every element is probably too complex. If you cannot simplify the diagram without losing the key insight, split it into two diagrams covering different aspects of the concept.

Diagrams should use consistent visual conventions: the same shapes for the same types of elements, the same arrow styles for the same types of relationships.

Video and GIFs

Short screen-capture videos and animated GIFs can be effective for demonstrating multi-step interactions — particularly those that involve timing, drag-and-drop, or animation that is difficult to show in a static screenshot.

Use video and GIF content sparingly and with clear purpose. Considerations:

• Videos must have captions or transcripts for accessibility.
• Animated GIFs autoplay and can be distracting — consider providing a static image with a link to the animated version.
• Both age quickly as the interface changes — have a plan for keeping them current.

Alt Text for Images

Every image in documentation must have descriptive alt text. Alt text is used by screen readers to describe images to readers with visual impairments, and by browsers when images fail to load.

Alt text describes what is in the image and why it is there in the context of the documentation. It is not a caption (which appears below the image for all readers) and it is not a description of the image's visual properties.

Decorative images — images that add visual interest but carry no informational content — should have empty alt text (alt="") so screen readers skip them.

Don't start alt text with "Image of..." or "Picture of..." — screen readers already announce that the element is an image, so this phrasing is redundant. See the Screen Reader Accessibility guide for this and other screen-reader-specific considerations.

Media File Names

Name media files descriptively, using this pattern: a numbered type prefix, followed by a hyphen-separated description.

Use lowercase letters and hyphens between words — not underscores or spaces — and no special characters. Hyphens are preferred over underscores because they're more broadly readable in URLs and by assistive technology.

File names show up in URLs and in some screen reader contexts. A file named 1-screenshot-settings-notifications-tab.png is more meaningful than screenshot-2024-11-15.png or img003.png.

Self-Audit Checklist

Before publishing, check images and video against these questions:

• Does every image communicate something text alone would not, rather than simply illustrating what's already described?
• Are screenshots cropped to show only the relevant portion of the interface?
• Do annotated screenshots use one consistent color, shape, and numbering convention across the knowledge base?
• Have screenshots been checked for accuracy against the current UI?
• Is any text-only dialog or message written as text rather than captured as a screenshot?
• For translated articles, are screenshots localized where the product UI supports it, or replaced with text where localization isn't feasible?
• Are images compressed and reasonably sized, not exported at unnecessarily high native resolution?
• Does every image have descriptive, contextual alt text — or empty alt text if purely decorative?
• Do videos have captions or transcripts?
• Are GIFs used sparingly, with a static alternative considered for distracting autoplay content?
• Do media file names follow the numbered-type-prefix, hyphenated, lowercase convention?