Merge branch 'main' into 2023-03-18_spelling-fix

contributing/content-style-guide.md

@@ -151,7 +151,7 @@ If you must use footnotes:
 Headers must adequately describe the content under it. Follow the same guidelines we use for writing titles. Each header on a page must be unique.
 
 Use H2 for headers, and H3 for subheaders. Articles must start with an H2 level header and cannot skip header levels. There must be content between a header and subheader, such as an introduction. When referring to headers, surround the header name with quotation marks.
-- **Use:** Under “User licenses”, view your total licenses.
+- **Use:** Under "User licenses," view your total licenses.
 
 For more information, see the [content model](/contributing/content-model.md#titles).
 
@@ -167,7 +167,7 @@ Every image must include alt text providing a textual equivalent of the visual i
 - 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.
+- Put multi-word titles, e.g. names of menu items, in double quotation marks ("").
 - 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
@@ -182,15 +182,16 @@ Alt text provides a short description of a screenshot's content to benefit peopl
 > Screenshot of the `Product name` + `UI element` shown. The `UI element` + `state of the element/controls`, and its `keyboard shortcut XYZ`, are outlined in dark orange.
 
 - For `Product name`, use the GitHub product or feature name, such as "GitHub Actions" or "GitHub repository," rather than just "GitHub."
+- Use a variable for the word `GitHub` as we do in running copy: `{% data variables.product.prodname_dotcom %}`
 - 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.
 
 ##### Examples
 
-> Screenshot of the committers by repository table. The horizontal kebab icon and "Download CSV report" button are outlined in dark orange.
+> Screenshot of the {% data variables.product.prodname_dotcom %} committers by repository table. The horizontal kebab icon and "Download CSV report" button are outlined in dark orange.
 
-> Screenshot of file options in a GitHub repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.
+> Screenshot of file options in a {% data variables.product.prodname_dotcom %} repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.
 
 ![Screenshot of file options in a GitHub repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.](./images/repository-code-button.png)
 

contributing/images-and-versioning.md

@@ -1,8 +1,8 @@
 # Creating and updating screenshots
 
-Screenshots complement text instructions for using GitHub. 
+Screenshots complement text instructions for using GitHub.
 
-**Use a screenshot when a user interface element is hard to find:** 
+**Use a screenshot when a user interface element is hard to find:**
 
 - The UI element is small or visually subtle.
 - The UI element is not immediately visible. For example, it is contained in a dropdown menu.
@@ -24,8 +24,6 @@ Don't use screenshots for simple steps where text does the job, or to show code
 
 The edit button for a repository's social media preview image is small and visually unobtrusive. It may be hard to find in the sea of repository settings.
 
-The screenshot is helpful to locate the button, as well as to understand the options it presents.
-
 As a bonus, the screenshot gives a visual reference for the aspect ratio required.
 
 ![Screenshot of an article showing text instructions and a UI screenshot for editing a social media image on a GitHub repository.](./images/screenshot-yes-social-preview.png)
@@ -100,6 +98,7 @@ Consider these factors when planning the screenshot strategy for an article or s
 ### Technical specs
 
 - PNG file format
+- Static images only
 - 144 dpi
 - 750–1000 pixels wide for full-column images
 - 250KB or less in file size
@@ -114,6 +113,12 @@ To be inclusive of all users, screenshots must:
 - **Have alt text** that describes the content of the image and the appearance of its highlighting, if any. [See alt text guidelines in our style guide.](./content-style-guide.md#alt-text)
 - **Be clear and crisp**, with text and UI elements as legible as possible.
 
+#### No animated GIFs
+
+Animated GIFs are not accessible. According to [WCAG 2.1 2.2.2](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html), motion that starts automatically or that lasts more than five seconds must have a pause, stop, or hide mechanism.
+
+Use text or static images instead.
+
 ### Visual style
 
 - Show a UI element with **just enough surrounding context** to help people know where to find it on their screen.
@@ -122,10 +127,21 @@ To be inclusive of all users, screenshots must:
   - 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).
   - If the software you need to screenshot is available in dark mode only, it's fine to use dark mode.
-- 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.
+- If your username and avatar appear, replace them with **Octocat's username and avatar**. [Find the Octocat avatar here.](https://avatars.githubusercontent.com/u/583231?v=4) Use the developer tools in your browser to replace your username with `@octocat` and to replace the URL of your avatar with the URL for Octocat's avatar, `https://avatars.githubusercontent.com/u/583231?v=4`.
+- Do not include a **cursor**.
 
  ![Screenshot of a comment box on a GitHub issue. A button labeled "Close issue" is outlined in dark orange.](./images/issue-comment-close-button.png)
 
+#### Visual style for dropdown menus
+
+If the primary goal in showing a dropdown menu is to help the reader locate the menu itself, show the menu closed:
+
+![Screenshot of an article showing instructions and a UI screenshot for selecting a folder as the publishing source for GitHub pages.](./images/screenshot-yes-pages-menu.png)
+
+If the primary goal in showing a dropdown menu is to help the reader distinguish among options within the menu, show the menu open. Capture open menus without focus (cursor or hover state). Showing menu items with a white background ensures contrast with the dark orange outline, where present:
+
+![Screenshot of an article showing instructions and a UI screenshot for locating the "Settings" menu item in the GitHub user account menu.](./images/screenshot-yes-account-menu.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.
@@ -140,7 +156,7 @@ The stroke is GitHub Primer color `fg.severe` (HEX #BC4C00 or RGB 188, 76, 0). T
 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.
+5. Optionally, star the dark orange rectangle to add it to your favorites.
 
 ### Adding a highlight to a screenshot
 
@@ -153,6 +169,8 @@ The stroke is GitHub Primer color `fg.severe` (HEX #BC4C00 or RGB 188, 76, 0). T
 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.
 
+**Note ⚠️**: A bug in Snagit may corrupt the corner rounding, causing rectangles to become ovals. If this occurs, delete and reinstall the GitHub Docs theme (Windows and Mac), or click and drag the yellow dot at the top right of the shape to reset corner rounding to 4 px (Mac only).
+
 ## 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.