From 0c352c08dd885e765b37bdb9b79d5fdcfaf74944 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Tue, 20 Jun 2023 11:59:05 -0700
Subject: [PATCH] Code annotation guidelines (#37158)

---
 contributing/code-annotations.md         | 77 ++++++++++++++++++++++++
 contributing/content-markup-reference.md | 43 +++++++++++--
 contributing/content-style-guide.md      |  3 +-
 3 files changed, 118 insertions(+), 5 deletions(-)
 create mode 100644 contributing/code-annotations.md

diff --git a/contributing/code-annotations.md b/contributing/code-annotations.md
new file mode 100644
index 0000000000..bde21e8c07
--- /dev/null
+++ b/contributing/code-annotations.md
@@ -0,0 +1,77 @@
+# Code annotations
+
+Code annotations help explain longer code examples by describing what a code example does and why. The annotations render next to the code samples in a two pane layout, so we can write longer annotations without making the code itself difficult to read. We only annotate full code examples, not snippets. Code annotations should add value when used and are not required for every code sample.
+
+Code annotations can be helpful for a variety of audiences. Often, code annotations will be used to explain key concepts to new users or specific choices to more experienced users.
+
+For new users, code annotations are a way to go beyond the high level overview of a code example and explain what each line of code does so that someone can understand the code as if a friend or coworker were guiding them through it.
+
+For more experienced users, code annotations can help them understand a code example and then tailor it to their specific needs. Annotations can explain why code was written a certain way so that the fundamentals are clear.
+
+## Enabling and adding code annotations
+
+1. Specify the `layout: inline` frontmatter property for the article.
+1. Create a code example using triple backticks.
+1. Specify a language for the code example after the triple backtick, followed by `annotate`. For example, ` ```yaml annotate` or ` ```ruby annotate`.
+1. Add annotations using comment tags (`#`, `//`, `<!--`, `%%`) within the code example. Annotations apply from the line below the comment to the next comment tag or the end of the code block.
+
+An annotated code example must start with a single line annotation. You can start with a blank annotation if you do not want to add an annotation to the first line of code.
+
+You must use the comment tag for the language that the code sample is written in. For example, `#` for YAML and `//` for Ruby.
+
+To enable code sample annotations, you must specify a language followed by the word `annotate` after the starting triple backtick code tag.
+
+Within code sample annotations:
+- Annotations use single-line comment style and must start with a comment tag that matches the code language: `#`, `//`, `<!--`, `%%`.
+- Annotations apply to the code from the line below the comment tag to the next comment tag or the end of the code block.
+- Multiline-style comments, such as `/*` are not supported.
+- You can include any number of spaces before the comment tag starts.
+- You can include any number of spaces after the comment tag ends.
+- To create a blank annotation, insert a comment tag with no text after it.
+- Anything after the comment tag will be parsed with Markdown. Links, versioning, and other styling will render as if they were written in Markdown.
+- Multiple sequential comments will create a single annotation.
+- Lines that do not start with a comment tag and are empty or only contain spaces will be ignored.
+- You must start the code section with a single line comment. If the first line (or section) of the code does not need an annotation, you can use a comment tag with no text to create a blank annotation.
+- For HTML style, you can include a closing tag, `<!-- -->`, after your annotations to maintain syntax highlighting; this will not impact how the annotations render.
+
+## Writing code annotations
+
+Introduce the overall purpose of a code example with an introduction before the code block and use annotations to explain what specific lines of code do and why they do it.
+
+Prioritize clarity in code annotations while trying to keep them as short as possible. People use code samples as a foundation for their own work, so annotations should help people understand the sample as it is written and how they might adapt the sample for other uses.
+
+Consider your audience when writing code annotations and do not assume people will know why an example is written a certain way.
+
+Annotations can be used to show the expected outcomes for the code that they annotate, but the results for the entire code example should be in the introduction for the code example or discussed after the example, whichever way best serves the audience.
+
+If a code example is changed, check that all annotations are still valid.
+
+## Example of an annotated code example
+
+    The following code example shows a workflow that posts a welcome comment on a pull request when it is opened.
+
+    ```yaml annotate
+    # The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
+    name: Post welcome comment
+    # The `on` keyword lets you define the events that trigger when the workflow is run.
+    on:
+      # Add the `pull_request` event, so that the workflow runs automatically
+      # every time a pull request is created.
+      pull_request:
+        types: [opened]
+    # Modifies the default permissions granted to `GITHUB_TOKEN`.
+    permissions:
+      pull-requests: write
+    # Defines a job with the ID `build` that is stored within the `jobs` key.
+    jobs:
+      build:
+        name: Post welcome comment
+        # Configures the operating system the job runs on.
+        runs-on: ubuntu-latest
+        # The `run` keyword tells the job to execute a command on the runner.
+        steps:
+          - run: gh pr comment $PR_URL --body "Welcome to the repository!"
+            env:
+              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              PR_URL: ${{ github.event.pull_request.html_url }}
+    ```
diff --git a/contributing/content-markup-reference.md b/contributing/content-markup-reference.md
index bb62a3a7bd..edcf1f44ee 100644
--- a/contributing/content-markup-reference.md
+++ b/contributing/content-markup-reference.md
@@ -6,14 +6,16 @@
   - [Usage](#usage)
 - [Callout tags](#callout-tags)
   - [Usage](#usage-1)
-- [Code sample syntax highlighting](#code-sample-syntax-highlighting)
+- [Code sample annotations](#code-sample-annotations)
   - [Usage](#usage-2)
-- [Octicons](#octicons)
+- [Code sample syntax highlighting](#code-sample-syntax-highlighting)
   - [Usage](#usage-3)
-- [Operating system tags](#operating-system-tags)
+- [Octicons](#octicons)
   - [Usage](#usage-4)
-- [Tool tags](#tool-tags)
+- [Operating system tags](#operating-system-tags)
   - [Usage](#usage-5)
+- [Tool tags](#tool-tags)
+  - [Usage](#usage-6)
 - [Reusable and variable strings of text](#reusable-and-variable-strings-of-text)
 - [Tables with codeblocks](#tables-with-codeblocks)
 - [Internal links with AUTOTITLE](#internal-links-with-autotitle)
@@ -62,6 +64,39 @@ Callouts highlight important information that customers need to know. We use sta
 
 For information on when to use callout tags, see the [style guide](content-style-guide.md).
 
+## Code sample annotations
+Code sample annotations help explain longer code examples by rendering comments as annotations next to the sample code. This lets us write longer explanations of code without cluttering the code itself. Code samples with annotations are rendered in a two pane layout with the code sample on the left and the annotations on the right. The annotations are visually emphasized when someone hovers their cursor over the code example.
+
+Code annotations only work in articles with the `layout: inline` frontmatter property. See "[Code annotations](./code-annotations.md)" for more information on how to write and style code annotations.
+
+### Usage
+
+    ```yaml annotate
+    # The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
+    name: Post welcome comment
+    # The `on` keyword lets you define the events that trigger when the workflow is run.
+    on:
+      # Add the `pull_request` event, so that the workflow runs automatically
+      # every time a pull request is created.
+      pull_request:
+        types: [opened]
+    # Modifies the default permissions granted to `GITHUB_TOKEN`.
+    permissions:
+      pull-requests: write
+    # Defines a job with the ID `build` that is stored within the `jobs` key.
+    jobs:
+      build:
+        name: Post welcome comment
+        # Configures the operating system the job runs on.
+        runs-on: ubuntu-latest
+        # The `run` keyword tells the job to execute the [`gh pr comment`](https://cli.github.com/manual/gh_pr_comment) command on the runner.
+        steps:
+          - run: gh pr comment $PR_URL --body "Welcome to the repository!"
+            env:
+              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              PR_URL: ${{ github.event.pull_request.html_url }}
+    ```
+
 ## Code sample syntax highlighting
 
 To render syntax highlighting in command line instructions, we use triple backticks followed by the term `shell`.
diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md
index 5546e76ece..0121cc8845 100644
--- a/contributing/content-style-guide.md
+++ b/contributing/content-style-guide.md
@@ -89,7 +89,8 @@ Avoid inline links in command names.
 
 ### Examples
 
-When code examples refer to a larger file, show the relevant section of the file, so that users understand how to edit their own code in context.
+When code examples refer to a larger file, show the relevant section of the file, so that users understand how to edit their own code in context. You can add code annotations to explain long code examples. See "[Code annotations](./code-annotations)" for more information.
+
 - **Use:**
 
 ```