Skip to main content
Visual media can make complex workflows clearer than text alone—but it comes with a maintenance cost. Every screenshot you publish is a commitment to update it when the UI changes. Every video becomes outdated when the flow it shows changes. The goal isn’t to avoid media. It’s to use it deliberately, so the clarity it adds outweighs the work of keeping it current.

​
When to use media

Not every step needs a screenshot. Not every concept needs a diagram. Before adding media, ask whether the content is genuinely clearer with it or whether clean prose and code examples would serve users just as well.

​
Screenshots

Use screenshots for tasks that are difficult to describe in words—especially UI-heavy workflows where users need to orient themselves visually, or where identifying the right interface element would be ambiguous without seeing it. Avoid screenshots for:
  • Simple actions users can’t easily misidentify (“click Save”)
  • Content that changes frequently—settings pages, dashboards, and feature-heavy UIs are expensive to maintain
  • Decorative purposes where the image doesn’t add information

​
GIFs

GIFs work well for short, looping demonstrations—showing an animation, revealing a multi-step interaction, or capturing a workflow that’s easier to follow visually than to describe step by step. Keep GIFs short. Files over a few seconds become large and slow to load, and long GIFs are harder for users to follow than a short video they can pause and rewind.

​
Videos

Use videos for abstract concepts that benefit from narration, or for long workflows where the sequence and timing matter. Videos are more accessible than GIFs for complex content—users can pause, rewind, and control playback speed. Host videos on an external platform like YouTube or Loom and embed them rather than serving video files directly. Video files significantly increase page load times.

​
Guidelines for every media type

​
File format and size

  • Use PNG for screenshots and diagrams. PNG preserves sharp edges and text.
  • Use WebP for photographs or images where file size matters. WebP is smaller than PNG and JPEG with comparable quality.
  • Use GIF only when animation is necessary. For static images, GIF offers no advantages over PNG.
  • Compress images before adding them to your repository. Tools like Squoosh reduce file sizes without visible quality loss.

​
Dimensions

  • Keep screenshots at their native resolution or scale down—never scale up, which introduces blurriness.
  • Standard documentation width is typically 800–1200px. Wider screenshots scale down automatically but may look small on mobile.
  • Crop screenshots tightly to the relevant UI. Surrounding chrome, empty space, and unrelated elements distract from what you’re showing.

​
Alt text

Every image needs descriptive alt text. Alt text makes images accessible to screen reader users and contributes to SEO. Write alt text that describes what the image shows and why it matters in context: 
<!-- Descriptive and contextual -->
![The API keys settings page showing a list of three active keys with their creation dates and last-used timestamps](/images/api-keys-settings.png)

<!-- Not useful -->
![Settings page](/images/api-keys-settings.png)
See Accessibility for more on writing effective alt text.

​
File naming

Use descriptive, kebab-case filenames that indicate the content: 
api-keys-settings.png       ✓
screenshot-2024-01-15.png   ✗
image1.png                  ✗
Descriptive filenames make it easier to find and replace outdated images, and they contribute marginally to image SEO.

​
Maintenance

Media is the most expensive part of documentation to maintain. A single UI redesign can make dozens of screenshots outdated simultaneously. A few practices that reduce maintenance burden:
  • Crop tightly to the relevant element. Screenshots that show only the component being discussed go out of date more slowly than full-page captures that include navigation, headers, and surrounding UI.
  • Avoid screenshots for frequently-changing content. If a settings page ships UI changes every quarter, consider whether descriptive prose is more maintainable than a screenshot.
  • Keep source files. Store uncompressed originals or layered files where possible, so screenshots can be updated without recapturing from scratch.
  • Document what each image shows. A comment in the MDX or a shared image manifest noting what content an image depicts makes it faster to identify outdated assets during review.

​
Frequently asked questions

Prefer text with screenshots as supplements, not replacements. Text is faster to scan, easier to search, and cheaper to update. Add a screenshot when users need to visually identify something in the UI or when a workflow would be genuinely confusing without seeing it. A common pattern is to describe the step in text and include a screenshot only for steps where visual orientation matters.
The fastest path is recapturing the specific screenshots that changed rather than batch-updating everything at once. Tightly cropped screenshots that focus on a single element change less frequently than full-page captures. When a major UI redesign ships, treat screenshot updates as a documentation sprint with a defined scope rather than an ongoing distraction.
GIFs loop automatically, require no user interaction, and embed directly in the page without a player. They work well for simple, short interactions where the loop is useful. Short videos are better for anything longer than a few seconds, anything that benefits from audio, or any workflow complex enough that users need to pause and reference specific frames. Videos also have better accessibility support—GIFs have no pause control and no alt text equivalent beyond a description in surrounding content.
If an image adds no information—a purely decorative separator or background element—use an empty alt attribute (alt="") to tell screen readers to skip it. But most images in documentation are informational, not decorative. When in doubt, write alt text.