Update placeholder guidance (#40258)

Co-authored-by: Felicity Chapman <felicitymay@github.com>

content/contributing/writing-for-github-docs/style-guide.md

@@ -86,7 +86,10 @@ Keep lines in code samples to about 60 characters, to avoid requiring readers to
 
 Within code blocks:
 - Specify the language of the sample after the first code fence. For a list of all supported languages, see "[Code languages](https://github.com/github/docs/blob/main/data/variables/code-languages.yml)" in the `github/docs` repository.
-- Do not use markup before the command output.
+- Do not use HTML to style or markup a code block.
+- Style any placeholders that people need to replace with their own values in all caps.
+  - **Use:** `git checkout -b BRANCH-NAME`
+  - **Avoid:** `git checkout -b <branch-name>`
 - Only use `$` before the command itself if you’re showing the command’s output in the same block.
   - If you show a command and the command's output, do not make the code block copyable.
 - If your code example includes `{` or `}` that should render, wrap that section in <code>&#123% raw %&#125;</code> <code>&#123% endraw %&#125;</code> to disable Liquid processing for that section.
@@ -102,7 +105,7 @@ Within code blocks:
     GITHUB_TOKEN: $&#123;&#123; secrets.GITHUB_TOKEN &#125;&#125;
     </pre>
 
-- If your code example includes content that should be parsed (for example, HTML tags to format text), wrap that section in `<pre>` `</pre>` tags to parse rather than escape the content in the section.
+- If your code example includes content that should be parsed, wrap that section in `<pre>` `</pre>` tags to parse rather than escape the content in the section.
 
 ### Commands
 
@@ -375,12 +378,12 @@ This text is only an example. Always use the license text from the project you a
 `````
 ## Legal notice
 
-Portions have been adapted from [PROJECT](/link/to/project) under the MIT license:
+Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:
 
 ```
 MIT License
 
-Copyright <YEAR> <COPYRIGHT HOLDER>
+Copyright YEAR COPYRIGHT-HOLDER
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
@@ -403,13 +406,13 @@ For any link that points to another {% data variables.product.prodname_docs %} p
 
 Usage examples:
 
-- For links to other pages: `For more information, see "[AUTOTITLE](/path/to/page)."`
-- For links to sections in other pages: `For more information, see "[AUTOTITLE](/path/to/page#section-link)."`
-- For links to a page with a tool selected: `For more information, see the TOOLNAME documentation in "[AUTOTITLE](/path/to/page?tool=TOOLNAME)."`
+- For links to other pages: `For more information, see "[AUTOTITLE](/PATH/TO/PAGE)."`
+- For links to sections in other pages: `For more information, see "[AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK)."`
+- For links to a page with a tool selected: `For more information, see the TOOLNAME documentation in "[AUTOTITLE](/PATH/TO/PAGE?tool=TOOLNAME)."`
 
-Same-page section links do **not** work with `AUTOTITLE`. Instead, type out the full header text: `For more information, see "[Header text](#section-link)."`
+Same-page section links do **not** work with `AUTOTITLE`. Instead, type out the full header text: `For more information, see "[HEADER-TITLE](#SECTION-LINK)."`
 
-For links to external documentation, type out the full article name: `For more information, see [Page or article title](https://some-docs.com/path/to/page) in the X documentation.`
+For links to external documentation, type out the full article name: `For more information, see [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.`
 
 Do not include quotation marks within a hyperlink.
 
@@ -464,12 +467,12 @@ For more information, see "[HEADER TITLE](#HEADER-TITLE)."
 To link to a specific header in a different article, use this format:
 
 ```
-For more information, see "[AUTOTITLE](path-to-article#HEADER-TITLE)."
+For more information, see "[AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE)."
 ```
 
 To link to two or more specific headers in a different article, use this format:
 ```
-For more information, see "[HEADER 1](path-to-article#HEADER-1)" and "[HEADER 2](path-to-article#HEADER-2)" in "ARTICLE TITLE."
+For more information, see "[HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1)" and "[HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2)" in "ARTICLE-TITLE."
 ```
 
 ### Links to a specific tool
@@ -509,6 +512,19 @@ Formatting unordered lists:
 
 When introducing a list, avoid phrasing like “the following” or “these”, terms which are difficult to localize. Instead, be descriptive, yet general enough to allow a list to scale or change without having to update the description.
 
+## Placeholders
+
+Style any placeholder text in all caps. If a placeholder is multiple words, connect the words with dashes (kebab-case). If you use a placeholder, explain what someone might replace it with. This helps people modify examples to fit their needs and helps identify placeholders for people who use assistive technology.
+
+**Use:**
+- In the following example, replace YOUR-REPOSITORY with the name of your repository. `git init YOUR-REPOSITORY`
+- Click **Add USERNAME.** Where USERNAME is the username of the person you want to add.
+
+**Avoid:**
+- `git init your repository`
+- `git init <your-repository>`
+- Click **Add _username_.**
+
 ## Procedural steps
 
 Procedures give readers a set of sequential steps to follow to complete a task. Always use numbered lists for procedures. Give readers all of the prerequisites or conceptual information they’ll need to complete the task before the procedure, rather than including it within a specific step.
@@ -1114,7 +1130,7 @@ Use bold to describe UI elements that can be interacted with.
 
 Use code formatting for branch names.
 - `main`
-- `<username>.github.io`
+- `USERNAME.github.io`
 
 ### Buttons
 

contributing/content-markup-reference.md

@@ -101,13 +101,17 @@ Code annotations only work in articles with the `layout: inline` frontmatter pro
 
 To render syntax highlighting in command line instructions, we use triple backticks followed by the language of the sample. For a list of all supported languages, see the [Code languages](https://github.com/github/docs/blob/main/data/variables/code-languages.yml) file.
 
+Do not use HTML to style or modify code samples.
+
 ### Usage
 
     ```shell
-    git init YOUR_REPO
+    git init YOUR-REPO
     ```
 
-Within the code sample syntax, use all uppercase text to indicate placeholder text or content that varies for each user, such as a user or repository name. By default, codeblocks will escape the content within the triple backticks. If you need to write sample code that parses the content (for example, to italicize text within `<em>` tags instead of passing the tags through literally), wrap the codeblock in `<pre>` `</pre>` tags.
+Within the code sample syntax, use all uppercase text to indicate placeholder text or content that varies for each user, such as a user or repository name. Introduce and explain any placeholders before the code sample so that people know what to replace the placeholder text with and because screen readers may not differentiate between upper and lowercase text, so placeholders may not be immediately apparent when read aloud. For example, "In the following example, replace `YOUR-USERNAME` with your GitHub username."
+
+By default, codeblocks will escape the content within the triple backticks. If you need to write sample code that parses the content, wrap the codeblock in `<pre>` `</pre>` tags.
 
 **Copy-able code blocks**
 
@@ -123,8 +127,8 @@ Octicons are icons used across GitHub’s interface. We reference octicons when
 
 If you're referencing an octicon that appears in the UI, identify whether the octicon is the entire label of the UI element (e.g., a button that is labeled only with "+") or whether it's only decorative, in addition to another label (e.g., a button is labeled "+ Add message").
 
- - If the octicon is the entire label, use your browser's developer tools to inspect the octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (e.g., `{% octicon "plus" aria-label="Add file" %}`). Occasionally, in the UI, the octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will.
- - If the octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the octicon in the docs as well (e.g., `"{% octicon "plus" aria-hidden="true" %} Add message"`).
+- If the octicon is the entire label, use your browser's developer tools to inspect the octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (e.g., `{% octicon "plus" aria-label="Add file" %}`). Occasionally, in the UI, the octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will.
+- If the octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the octicon in the docs as well (e.g., `"{% octicon "plus" aria-hidden="true" %} Add message"`).
 
 If you're using the octicon in another way, such as using the "check" and "x" icons to reflect binary values in tables, use the `aria-label` to describe the meaning of the octicon, not its visual characteristics. For example, if you're using a "x" icon in the "Supported" column of a table, use "Not supported" as the `aria-label`. For more information, see [Tables](./content-style-guide.md#use-clear-consistent-symbols-and-labels) in the style guide.