Revise screenshot guidelines (#34281)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>

contributing/content-style-guide.md

@@ -138,7 +138,51 @@ For more information, see the [content model](/contributing/content-model.md#tit
 
 ### Alt text
 
-Every image must include an alt attribute that provides a complete description of the image for the user. For more information, see “[Accessibility guidelines for images and videos](https://review.docs.microsoft.com/en-us/help/contribute/contribute-accessibility-multimedia)” in the Microsoft Docs Contributor Guide. Note that you'll need to be logged on to your Microsoft account to be able access this Microsoft resource.
+Every image must include alt text providing a textual equivalent of the visual information.
+
+- Express the core idea or meaning of the image, rather than describing it literally.
+- Use 40–150 characters.
+- End with a period.
+- Don't start with "Image..." or "Graphic...". Screen readers say this automatically.
+- Do begin with the _type_ of graphic: "Screenshot of..." or "Diagram that shows..."
+- Follow standard language used to describe UI elements in article text.
+- Put multi-word titles, e.g. names of menu items, in quotes.
+- If an area of the image is visually highlighted, describe how. This enables screen-reader users to understand and describe to a sighted friend/colleague what to look for from a visual language standpoint.  
+
+#### Alt text for screenshots
+
+Follow this format:
+
+> Screenshot of the `Product name` + `UI element` shown. The `UI element` + `state of the element/controls`, along with its `keyboard shortcut XYZ`, are highlighted with `visual highlight mechanism`.
+
+- For `Product name`, use the GitHub product or feature name, such as "GitHub Actions" or "GitHub repository," rather than just "GitHub."
+- Describe UI elements consistently with written documentation.
+- Be flexible with word order when needed for clarity.
+  - For example, write "Screenshot of the Debug menu in Visual Studio Code..." rather than "Screenshot of the Visual Studio Code Debug menu...," to avoid multiple nouns in a row.
+
+##### Example
+
+> Screenshot of file options on a GitHub repository. A green button with an arrow indicating a dropdown menu, labeled "Code," is highlighted with an orange outline.
+
+![Screenshot of file options on a GitHub repository. A green button with an arrow indicating a dropdown menu, labeled "Code," is highlighted with an orange outline.](../images/repository-code-button.png)
+
+#### Alt text for diagrams and graphs
+
+Explain the information conveyed in the diagram or graph in text on the page. 
+
+Use alt text to express the core idea of the image, without duplicating the webpage text.
+
+##### Example
+
+> Diagram showing a five-step process by which a GitHub Actions runner can be automatically added to named classes of runners and then requested by specific jobs.
+
+[See accompanying explanation of this diagram in the Actions documentation.](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners#architectural-overview-of-larger-runners) 
+
+#### Alt text for images of command-line interfaces
+
+Do not use screenshots of command-line interfaces to convey commands and their output. Instead, directly provide the commands a user should use. For more information, see the "[Commands](#commands)" section of the style guide.
+
+When using a screenshot of a command-line interface to show user interface elements, follow standard alt text guidelines for screenshots.
 
 ### Filenames
 

contributing/images-and-versioning.md

@@ -1,35 +1,99 @@
 # Creating and updating screenshots
 
-Screenshots are used to help readers with the flow in articles like procedures (as in "[Creating a repository from a template](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template)"), and conceptual articles about areas of the UI (as in "[Configuring notifications](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#about-participating-and-watching-notifications)").
+Screenshots complement text instructions for using GitHub. Use a screenshot when one or both of the following apply:
 
-## Best practices for taking screenshots
+- The relevant **area of the interface has multiple choices**, which would cause confusion without a visual cue.
+- A key **interface element is small, subtle**, or otherwise hard to find.
 
-- Screenshots enhance our content but can't replace it. 
+Don't use screenshots for simple steps where text does the job, or to show code commands or outputs.
-- Include descriptive alt text for better accessibility. See our [content style guide](./content-style-guide.md#alt-text) for more information.
 
-  `![Add mandatory message button](/assets/images/enterprise/site-admin-settings/add-mandatory-message-button.png)`
+## Pros and cons of screenshots
-- Ensure we're publishing strong standalone content along with screenshots.
-- When replacing an existing image (such as for an updated button in the UI), best practice is to retain the image's filename. If you must change an image filename, search the help docs repository for other references to that image and update all references to the original filename. If the image is used in deprecated versions of GHES documentation, please don't change the filename.
-- Screenshots should have descriptive names to make them easier to find. For example, use the name `gist-embed-link.png` instead of `right_side_page_03.png`.
-- Try to avoid overly large screenshots. For example, if you're trying to bring attention to a button, don't take a shot of the entire page. Focus on the area around the button instead. Crop down near the focal point of the image, but leave enough of a margin around it so that some other elements of the page are visible to provide context.
-- Ensure screenshot is always taken in light mode. 
-- Replace your username and avatar with [Octocat's](https://github.com/octocat) username and avatar. You can do this using the developer tools in your browser to edit the rendered page.
-- When taking a screenshot, select the portion of the page that needs focus instead of the entire page.
 
+Consider these in your decision-making.
 
-    Here's an example of a good cropping:
+### Pros of screenshots
 
-    ![good cropping example](../assets/images/good-screenshot-example.png)
+- Screenshots make articles more visually scannable.
+- Screenshots make instructions easier to follow, especially for people who have difficulty reading.
+- When supplied with alt text, screenshots help blind and low-vision users collaborate with sighted colleagues.
 
-    Here's an example of a bad cropping:
+### Cons of screenshots
 
-    <img src="../assets/images/bad-screenshot-example.png" alt="bad cropping example" width="600"/>
+- Screenshots privilege sighted users.
+- Screenshots add length and load time to articles.
+- Screenshots increase the volume of content that needs to be maintained.
+- When captured at different pixel dimensions and degrees of zoom, screenshots can look confusing.
+
+## Guidelines for screenshots on GitHub Docs
+
+### Technical specs
+
+- PNG file format
+- 144 ppi ("retina" or 2x on Mac)
+- 750–1000 pixels wide for full-column images
+- 250KB or less in file size
+- Descriptive file names: `gist-embed-link.png` instead of `right_side_page_03.png`
+
+### Accessibility
+
+To be inclusive of all users, screenshots must:
+
+- **Be accompanied by complete instructions** on the webpage, with no information conveyed entirely in visual form.
+- **Be full contrast** as in the interface itself, with nothing obscured or reduced in opacity or color contrast.
+- **Have alt text** that describes the meaning of the image and the appearance of its highlighting, if any. [See alt text guidelines in our style guide.](../assets/contributing/content-style-guide.md#alt-text)
+- **Be clear and crisp**, with text and UI elements as legible as possible.
+
+### Visual style
+
+- Show a UI element with **just enough surrounding context** to help people know where to find it on their screen.
+- **Reduce negative space**, for example in input fields, by resizing your browser window until optimal.
+- Show interfaces in **light theme** to ensure contrast between the interface and the orange highlight.
+  - For GitHub, select "Light default" in your account's [appearance settings](https://github.com/settings/appearance).
+  - For VSCode, select "GitHub Light Default" in the free [GitHub Theme extension](https://marketplace.visualstudio.com/items?itemName=GitHub.github-vscode-theme).
+- Replace your username and avatar, if they appear, with **[Octocat's](https://github.com/octocat) username and avatar**. You can do this using the developer tools in your browser to edit the rendered page.
+
+ ![Screenshot of a comment box on a GitHub issue. A button labeled "Close issue" is highlighted with an orange outline.](../images/issue-comment-close-button.png)
+
+## Adding highlighting in Snagit
+
+Use [Snagit](https://www.techsmith.com/screen-capture.html) to apply a contrasting stroke around the UI element being discussed.
+
+![Screenshot of four options menus on a GitHub repository. The menu labeled "Fork" shows a fork count of 58.5k and is highlighted with an orange outline.](../images/repository-fork-button.png)
+
+### Importing the GitHub Docs theme into Snagit
+
+1. Download [`snagit-theme-github-docs.snagtheme`](../images/snagit-theme-github-docs.snagtheme) to your computer.
+2. Open Snagit and select the Shape tool.
+3. Under "Quick Styles," select "Import...".
+4. Select the Snagit theme from your computer's files. This will install the shape preset.
+5. Optionally, star the orange rectangle to add it to your favorites.
+
+### Adding a highlight to a screenshot
+
+1. Open a screenshot you'd like to highlight.
+2. If the image is larger than 1000 pixels, resize it to 1000 pixels so that the stroke will be clearly visible.
+3. With the GitHub Docs theme open in the Shapes sidebar, select the orange rectangle.
+4. Drag and drop across the image to create a rectangle. Adjust height and width by dragging edges.
+5. Adjust the space between the UI element and the stroke so it's about the width of the stroke itself.
+6. Export image to PNG.
+7. Keep the editable Snagit file with the extension `.snagx` on your computer in case you need to change the file later.
+
+## Replacing screenshots
+
+When replacing an existing image (such as for an updated button in the UI), best practice is to retain the image's filename.
+
+If you must change an image filename, search the docs repository for other references to that image and update all references to the original filename.
+
+If the image is used in deprecated versions of GHES documentation, don't change the filename.
   
 ## Versioning images in Markdown content
 
-Some images apply to all GitHub plans (Free, Pro and Team; GitHub Enterprise Server; GitHub AE; and GitHub Enterprise Cloud). In this case, there is no versioning required. When an image does differ from plan to plan or changes in a newer release of GitHub Enterprise server or GitHub AE, the images need to be versioned with [Liquid](liquid-helpers.md) conditional statements. The Liquid conditional versioning may need to be added when the content is initially created, or may need to be added when the content is updated for a feature update or Enterprise release.
+Some images apply to all GitHub plans (Free, Pro and Team; GitHub Enterprise Server; GitHub AE; and GitHub Enterprise Cloud). In this case, there is no versioning required.
+
+When an image does differ from plan to plan or changes in a newer release of GitHub Enterprise server or GitHub AE, the images need to be versioned with [Liquid](liquid-helpers.md) conditional statements. The Liquid conditional versioning may need to be added when the content is initially created, or may need to be added when the content is updated for a feature update or Enterprise release.
 
 ### Image locations
+
 Images are located in the `/assets/images` directory. This directory has some folders that can be used to organize content by plan and release number.
 
 - `/assets/images/enterprise/github-ae`: Images that are _only_ applicable to GitHub AE (and not applicable to any other plan).
@@ -63,7 +127,3 @@ Your Liquid conditional would look like this:
 When the 3.0 release is deprecated, the `/assets/images/enterprise/3.0` directory will be removed. 
 
 The numbered release directory should contain images that apply to that release number only or to that release number and earlier. For example, images in `/assets/images/enterprise/2.22` should contain images that apply to 2.22 only or 2.22 and earlier.
-  
-## Resources
-
-- [GIF Brewery](http://www.helloresolven.com/portfolio/gifbrewery/) (used for converting video captures to GIF format)