About screenshots in GitHub Docs
There are positives and negatives to adding a screenshot. Screenshots make articles more visually scannable and make instructions easier to understand, especially for people who have difficulty reading. When supplied with alt text, screenshots help blind and low-vision users collaborate with sighted colleagues.
On the other hand, screenshots privilege sighted users, add length and load time to articles, and increase the volume of content that needs to be maintained. When captured at different pixel dimensions and degrees of zoom than the reader is using, screenshots can be confusing.
Therefore, we only add screenshots to GitHub Docs when they meet our criteria for inclusion.
Criteria for including a screenshot
Use a screenshot to complement text instructions when an element of the user interface (UI) is hard to find:
- The element is small or visually subtle.
- The element is not immediately visible. For example, the element is contained in a dropdown menu.
- The interface has multiple competing choices that can cause confusion.
Do not use screenshots for procedural steps where text alone is clear, or to show code commands or outputs.