Skip to main content
Adding a screenshot can feel like the quickest way to make a page more helpful. Sometimes it is. Other times, the screenshot repeats the instructions, goes stale after the next product update, and makes the important part harder to find. Start with the question the visual needs to answer. If there isn’t one, you probably don’t need the visual.

​
Use screenshots to show location or state

A screenshot is useful when readers need to recognize something they can see:
  • Where a setting lives in a crowded interface
  • Which status confirms that a deployment worked
  • What a correctly configured screen looks like
Crop to the part that matters. A full-screen capture with one tiny button circled in red makes readers search the image before they can continue. Skip the screenshot when the interface is simple enough to describe in a sentence, such as “Select Settings, then API keys.” Text is faster to scan, easier to update, and searchable.

​
Use frames to give visuals context

<Frame> separates an image or video from the surrounding page and can add a caption:
Example of a framed image
The alt text and caption have different jobs. Alt text conveys what a reader needs from the image. The caption explains why the image is here or points out something worth noticing. Repeating the same sentence in both doesn’t help. “Screenshot of dashboard” is weak alt text because it leaves out the useful part. “Deployment dashboard showing a successful production build” tells the reader which state the image demonstrates. Use alt="" for a purely decorative image. For an instructional image, describe the information, not every color, border, and menu visible on the screen. Readers can click images to zoom in by default. Add noZoom to an image when zooming doesn’t help, like a small icon or a logo that links somewhere.

​
Use diagrams to explain relationships

When the hard part is understanding how several things connect, a diagram is usually more helpful than a screenshot. Request flows, system boundaries, state changes, and branching processes are good candidates. Mintlify renders Mermaid diagrams from a text definition, so you can review changes to the diagram alongside the rest of your content:
Example of a Mermaid diagram
This diagram is useful because the order and relationship between stages are the point. A screenshot of GitHub would show the interface, but not the workflow as clearly. Introduce a diagram in the text and summarize its takeaway. That context helps everyone, including readers who use a screen reader or can’t comfortably inspect a large diagram. Mintlify adds zoom and pan controls to larger diagrams, but a diagram that needs them may be trying to show too much at once.

​
Plan for the next product update

Before publishing a visual, ask what will make it stale. Screenshots often contain button labels, navigation, account data, dates, and feature states that change independently of the instructions. Remove personal or internal information, and keep the source file for diagrams your team may need to update. During product reviews, check the visuals on every affected page, not only the prose around them. If your site supports light and dark mode, a screenshot taken in one mode can look out of place in the other. Take a screenshot in each mode and show the right one with the dark:hidden and hidden dark:block classes:
Example of light and dark mode screenshots
Next up: Cards and links for navigation—use visual weight to guide readers to another page.