Writing alt text for screenshots in documentation

Screenshots are everywhere in software docs, and most of them have alt text like screenshot, image, or the original file name. Sometimes there's none at all. When I edit a guide, the images are often the last thing anyone has looked at closely.

Alt text matters more in docs than people think. Screen reader users hear it instead of seeing the image. It shows up when an image fails to load, for example on a slow connection or after someone renames a folder in the repo. And it's text, so it can be searched and translated, which a picture of text can't.

Here's how I approach it.

Ask what the screenshot is for

Before writing anything, I ask one question: why is this image here? In docs, the answer is almost always one of these:

• It shows where something is (a button, a menu, a field).
• It shows what you should see after a step, so the reader can confirm it worked.
• It shows a specific value or setting the reader has to match.
• It's decoration, and the surrounding text already says everything.

The alt text should carry that purpose, not a full inventory of the screen. A settings page might have thirty controls on it, but if the step is about one checkbox, that checkbox is what the alt text is about.

Describe the state, not the pixels

Compare these two:

![Screenshot of the settings page](images/settings.png)

![The Notifications tab with "Email me when a build fails" turned on](images/settings.png)

The first tells me nothing I couldn't guess. The second tells me exactly what the screen should look like after the step, which is the whole reason the screenshot exists.

A few habits that help:

• Skip "image of" and "screenshot of". Screen readers usually announce that it's an image already. Start with the content.
• Use the exact UI labels, with the same capitalisation as the interface. If the button says "Save changes", the alt text says "Save changes", not "the save button".
• Include values that matter. If the reader needs to pick "UTF-8" or set a timeout to 30, put that in the alt text.
• Keep it to a sentence or two. If you need more, the information probably belongs in the body text.

Don't hide instructions in the image

This is the problem I find most often. A step says "Configure the options as shown below", and the actual settings only exist in the screenshot. Anyone who can't see the image, or whose image didn't load, is stuck.

The fix isn't longer alt text. It's moving the information into the step itself:

3. In **Format**, select **CSV**, and in **Encoding**, select **UTF-8**.

   ![The Export dialog with CSV and UTF-8 selected](images/export.png)

Now the step works without the image, and the screenshot becomes a confirmation. The alt text can stay short because the text above it does the heavy lifting.

When empty alt text is right

Not every image needs a description. If a screenshot only repeats what the text already says, or it's a decorative banner, an empty alt is the honest choice. In Markdown that's ![](images/banner.png), which renders as alt="". Screen readers generally skip images with empty alt text instead of reading out the file name.

The difference between "empty on purpose" and "forgot to write it" is invisible in the source, though. In repos I work on, I like a short HTML comment next to deliberate ones, so the next editor doesn't "fix" it:

<!-- decorative, text above covers it -->
![](images/banner.png)

A quick check before review

To find the obvious problems in a docs folder, I use a single grep. It looks for three patterns: empty or generic alt text, alt text that is a file name, and alt text that starts with "image of" or "screenshot of".

grep -rniE \
  -e '!\[(image|screenshot|picture|img)?\]\(' \
  -e '!\[[^]]*\.(png|jpe?g|gif|webp)\]' \
  -e '!\[(an? )?(image|picture|screenshot|photo) (of|showing)' \
  docs/

-r searches the folder recursively, -n adds line numbers, -i ignores case, and -E enables extended regular expressions. Each -e adds one pattern. On a test file it prints something like:

docs/setup.md:3:![](images/settings.png)
docs/setup.md:5:![screenshot](images/login.png)
docs/setup.md:7:![Screenshot 2026-03-02 at 10.14.png](images/export.png)
docs/setup.md:11:![image of the dashboard](img/dash.png)

It's not a verdict. The empty alt on line 3 might be deliberate, and the check can't tell whether a real description is accurate. It only catches images written in Markdown syntax, not HTML <img> tags. But it gives me a list to work through, which beats scrolling every page looking for images.

Keep it in sync

The last thing: alt text goes stale with the UI. When a button gets renamed and someone updates the screenshot, the alt text often keeps the old label. When I review a docs change that touches an image, I read its alt text against the new screenshot. It takes a few seconds, and it's usually the only place the old wording survives.