Skip to content

chore: document the criteria for including screenshots #779

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rohalskyy wants to merge 1 commit into
base: main
Choose a base branch
from
+23 −1
Open

chore: document the criteria for including screenshots #779

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 23 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,29 @@ By default, images take up the entire width of the content container. To make th

### Criteria for including a screenshot

See the GitHub's [Creating screenshots](https://docs.github.com/en/contributing/writing-for-github-docs/creating-screenshots) guide.
A screenshot should add something the text cannot. Default to **not** adding one — it should support the text, not repeat it. If the text alone already gets the point across, leave the screenshot out. See GitHub's [Creating screenshots](https://docs.github.com/en/contributing/writing-for-github-docs/creating-screenshots) guide for the general approach.

**Add a screenshot when:**

- The element is hard to find or its location isn't obvious (for example, hidden in a menu or dropdown, or one control among many).
- The interface has competing choices a user could easily get wrong.
- It shows a visual result or layout that's hard to describe in words (a rendered preview, a complex dialog, a chart or diagram).
- It's an orientation checkpoint in a long, multi-step procedure.

**Skip a screenshot when:**

- The text next to it already describes everything it shows.
- It's a standard, self-evident control (a labeled button, a simple form, a plain table) recognizable from its label.
- It's a single icon — reference it inline with the `<Icon>` component instead.
- All its information is already in the text — instead, put the location into the step (for example, "click [icon] next to the [item] and select [option]").
- It shows text, code, or output — use real text instead.
- It contains volatile or demo data (percentages, counts, test names) or personal information.

**Capturing screenshots:**

- Crop to the relevant part of the screen and leave out UI that doesn't help illustrate the point.
- Use realistic content — no lorem ipsum or personal data.
- For a dialog with collapsible sections, capture it in the default (collapsed) state with a bit of realistic data — not everything expanded. It's what users see, and it avoids repeating fields the text already lists.

## File-based/String-based content differentiation

Expand Down
Loading