How to use images, screenshots and videos

A good screenshot can make a confusing workflow obvious. It also comes with a bill. Every screenshot you publish is a promise to recapture it when the interface changes, and every video goes stale the day the flow it shows is redesigned.

The goal is not to avoid media. It is to use it deliberately, so the clarity it adds is worth the upkeep it costs.

When to use media

Not every step needs a screenshot, and not every concept needs a diagram. Before you add one, ask whether it actually clarifies anything. Tight prose and a code example are often just as clear, and far cheaper to keep correct.

Screenshots

Use screenshots when words struggle: UI-heavy tasks where the reader needs to orient themselves, or where the right control would be ambiguous without seeing it.

Skip them for:

• Actions nobody can get wrong, like “click Save”.
• Interfaces that change often — settings pages, dashboards, busy feature screens.
• Decoration. An image that adds no information is just weight.

GIFs

GIFs suit short, looping demonstrations: an animation, a quick multi-step interaction, a gesture that is easier to watch than to read.

Keep them short. A GIF longer than a few seconds is a large file and a hard thing to follow, because the reader cannot pause it. Past that length, a video is kinder.

Videos

Video suits abstract concepts that benefit from narration, and long workflows where sequence and timing matter. Readers can pause, rewind and slow a video down, which makes it easier to follow than a GIF for anything complex.

Reed has no video component. Host videos on a platform built for them and link to them from the page, with a sentence that says what the video covers and how long it runs. If you try embedding a player with raw HTML, run reed check and review the built page before you rely on it — Reed makes no promises about embeds. Either way, put the information the reader needs in the page text too. See How to create accessible documentation for captions and transcripts.

Add images to a page

Keep images next to the page and use a relative path

Put image files inside your content directory, near the pages that use them, and reference them with standard markdown image syntax and a path relative to the page file:

mdx

![The Settings page with the API keys section expanded](./images/api-keys-settings.png)

The content directory is copied into the Astro project Reed generates, not straight into the output. An image referenced relatively from a page is processed at build time and written to the output’s _astro/ directory under a hashed filename, alongside the site’s other processed assets — and it may be converted on the way (a PNG can come out as .webp), so do not link to the file by its original name. See Build output for the whole tree.

Two things to avoid:

• Root-relative image paths. Reed does not serve the content directory at the site root, so a path such as /docs/guides/images/api-keys-settings.png produces no file in the output and does not point at your image.
• An <img> tag for a local file. A relative src on raw HTML is not resolved against the page file; it is emitted unchanged, so the image is broken. Use markdown image syntax for local images. <img> is fine for images hosted at an absolute URL.

Links are different: Reed never touches link targets, and a page link must carry the base prefix. How to link documentation pages effectively covers that rule.

Frame images that need context

Frame wraps an image in a bordered surface and gives it an optional hint above and caption below, in a fixed order so screenshots read consistently across the site.

Put a markdown image directly inside the Frame, on its own line with blank lines around it:

mdx

<Frame caption="API keys are listed newest first.">

![The API keys table with three active keys and their last-used dates](./images/api-keys-table.png)

</Frame>

The image is processed and copied into the build like any other markdown image. It no longer needs a <div> around it. For an image at an absolute URL, an <img> with alt works as the child instead. An empty Frame still fails the page with DS-S02. See Images and files.

The caption is visible text for everyone. It supplements the alt text; it does not replace it. Layout and surfaces documents both props.

Guidelines for every image

Format and size

• PNG for screenshots and diagrams. It keeps text and edges sharp.
• WebP for photographs, or anywhere file size matters more than pixel-perfect edges.
• GIF only when you need animation. For a still image it has no advantage over PNG.
• Compress before you commit. A tool such as Squoosh cuts file size without visible loss. Your images live in git, and every version of every screenshot stays in the repository history forever — a 4 MB capture you replace ten times is 40 MB your whole team clones.

Dimensions

• Capture at native resolution and scale down if you must. Never scale up; it blurs.
• Aim for roughly 800–1200px wide. Wider images are shrunk to fit the content column and become hard to read, especially on phones.
• Crop tightly to the part of the interface you are talking about. Window chrome, empty space and unrelated panels pull the eye away from the point.

Alt text

Every image needs alt text. It is what a screen reader announces, what appears when the image fails to load, and part of what search engines read.

Reed enforces this. reed check reports DS-A01 — an error, not a warning — for any markdown image or <img> without non-empty alt text, and the build fails with it. See the diagnostics catalog.

Describe what the image shows and why it matters here:

mdx

![The API keys page listing three active keys with their creation dates and last-used times](./images/api-keys-settings.png)

Alt text like “Settings page” passes the check and helps no one. The check guarantees alt text exists; it cannot judge whether it is useful. That part is on you.

File names

Use descriptive, kebab-case names that say what the image shows:

text

api-keys-settings.png       good
screenshot-2024-01-15.png   bad
image1.png                  bad

A descriptive name makes an outdated image easy to find and replace, and helps image search a little.

Keep media maintainable

Media is the most expensive part of documentation to keep current. One redesign can make dozens of screenshots wrong at once, and unlike text, nothing flags them — a stale screenshot still builds.

Habits that reduce the cost:

• Crop tightly. A capture of one panel survives far more UI changes than a full-page capture that includes navigation, headers and everything around it.
• Skip screenshots of fast-moving screens. If a page of the product changes every quarter, prose will outlast any picture of it.
• Keep source files. Store uncompressed originals or layered files, outside the content directory, so an update is an edit rather than a full recapture.
• Make images findable. Descriptive file names and specific alt text let you grep for every image that shows a given screen when that screen changes. Because the images live in git, git log tells you when each was last updated.

Frequently asked questions

Should step-by-step instructions use screenshots or text?

Text first, screenshots as support. Text is faster to scan, searchable, and cheaper to update. Add a screenshot only where the reader needs to recognize something visually, or where the step would genuinely confuse without it. Describe each step in words and reserve images for the moments that need orientation.

How do I handle screenshots when the UI changes?

Recapture only the images that actually changed, not everything at once. Tightly cropped captures change far less often than full-page ones. When a large redesign ships, treat the screenshot update as a scoped piece of work with an owner and an end date, rather than a background chore that never finishes.

Should I use a GIF or a short video?

GIFs loop on their own, need no player, and suit a short interaction where the loop helps. Anything longer than a few seconds, anything with narration, or anything a reader will want to pause on belongs in a video. Videos are also more accessible: a GIF has no pause control and no captions, so the surrounding text has to carry its meaning.

What about purely decorative images?

Reed does not accept an empty alt attribute as a way to mark an image decorative; DS-A01 requires non-empty alt text on every image. In documentation that is rarely a loss, since almost every image should carry information. If an image really is only decoration, the simplest fix is to remove it.