THE GITHTML FIELD GUIDE
Write screenshot alternatives that explain the useful information
Write alternative text that communicates why the screenshot is included, not a complete inventory of every visible pixel. Put detailed instructions, values, and important conclusions in the surrounding HTML. A screenshot's alternative should complement that explanation and avoid repeating an entire paragraph that the reader will encounter immediately afterward.
Start with the screenshot's job
Ask which question the screenshot answers. In a setup guide, it may identify the location of an export control. In a review report, it may demonstrate an error state. In a comparison, it may show a layout difference. The same image can need different wording in these contexts because its purpose changes.
A filename or a generic label such as Screenshot does not communicate that purpose. Instead, describe the relevant state or control in plain language. Avoid adding unverified interpretations to the alternative text. If the image shows an error banner, state what it shows; do not infer the underlying cause unless the document has separate evidence for that conclusion.
Keep instructions out of pixels
If readers must follow a sequence of actions, write those actions as text next to the screenshot. Include the control names and expected result so the procedure remains usable without seeing the image. A long block of text inside the alt attribute is difficult to scan and cannot offer the same structure as paragraphs or a numbered list.
For dense evidence, provide a visible explanation or transcription of the relevant values. Do not transcribe every incidental menu item when only one field matters. Remove or redact unrelated sensitive information before publication, and verify that the text alternative does not accidentally reintroduce data removed from the visible image.
Review redundancy and missing meaning
Read the surrounding paragraph, alternative text, and caption in sequence. They should work together without repeating the same sentence three times. If the image is purely decorative and adds no information, an empty alternative may be appropriate. That decision depends on the document's meaning, not whether the image looks visually attractive.
- Write the reason the screenshot is present in one sentence.
- Name the relevant state, control, or comparison in the alternative.
- Put lengthy steps and exact values into ordinary HTML.
- Check whether the caption adds useful context rather than duplication.
- Review the page with images unavailable.
- Confirm that any redaction also covers captions, alternatives, and nearby explanatory text.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.