Deprecate contributing directory (#45581)
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>
This commit is contained in:
Ethan Palm
@@ -2,20 +2,18 @@
|
||||
|
||||
Check out our [contributing guide](../CONTRIBUTING.md) to see all the ways you can participate in the GitHub docs community :sparkling_heart:
|
||||
|
||||
Visit "[Contributing to GitHub Docs documentation](https://docs.github.com/en/contributing)" for additional information about how to write and collaborate the GitHub Docs way.
|
||||
|
||||
Here, you'll find additional information that might be helpful as you work on a pull request in this repo.
|
||||
|
||||
- [development](./development.md) - steps for getting this app running on your local machine
|
||||
- [codespace](./codespace.md) - use GitHub Codespaces to work on documentation markdown files
|
||||
- [content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site
|
||||
- [content style guide](./content-style-guide.md) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
|
||||
- [content model](./content-model.md) - the content types that make up GitHub Docs and how to write them
|
||||
- [content templates](./content-templates.md) - handy templates to get you started with a new article
|
||||
- [deployments](./deployments.md) - how our staging and production environments work
|
||||
- [liquid helpers](./liquid-helpers.md) - using liquid helpers for versioning in our docs
|
||||
- [translations guide for writers](./translations-for-writers.md) - making sure your content is ready to be translated
|
||||
- [node versions](./node-versions.md) - our site runs on Node.js
|
||||
- [permalinks](./permalinks.md) - permalinks for article versioning
|
||||
- [redirects](./redirects.md) - configuring redirects in the site
|
||||
- [troubleshooting](./troubleshooting.md) - some help for troubleshooting failed and stalled status checks
|
||||
- [Reusables](https://docs.github.com/en/contributing/writing-for-github-docs/creating-reusable-content#about-reusables) - We create reusables and call them from articles to help us keep content that is used in multiple places up to date.
|
||||
- [Variables](https://docs.github.com/en/contributing/writing-for-github-docs/creating-reusable-content#about-variables) - We use variables the same way we use reusables. Variables are for short strings of reusable text.
|
||||
- [Tests](/tests/README.md) - We use tests to ensure content will render correctly on the site. Tests run automatically in your PR, and sometimes it's also helpful to run them locally.
|
||||
|
||||
You can also read the READMEs in the `src/` directory to learn more about the features of the docs site.
|
||||
|
||||
@@ -1,79 +1 @@
|
||||
# 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.
|
||||
|
||||
You can annotate multiple code examples in a single article, but keep in mind that each annotation increases the complexity of an article and adds repetitive navigation tasks for people using screen readers. If you have multiple code examples in an article, consider whether they can be combined into a single example.
|
||||
|
||||
## 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 JavaScript.
|
||||
|
||||
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 should include a closing tag, `<!-- -->`, after your annotations to maintain syntax highlighting.
|
||||
|
||||
## 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 }}
|
||||
```
|
||||
The content in the `contributing` directory has been deprecated. See "[Annotating code examples](https://docs.github.com/en/contributing/writing-for-github-docs/annotating-code-examples)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,34 +1 @@
|
||||
# Working in a codespace
|
||||
|
||||
This document describes how to use GitHub Codespaces for working on articles for docs.github.com.
|
||||
|
||||
## About GitHub Codespaces
|
||||
|
||||
GitHub Codespaces allows you to work in a development environment that's hosted remotely from your machine. You can get started very quickly, with no need to set up the working environment, and without having to download files to your local computer.
|
||||
|
||||
**Note**: GitHub Codespaces is currently only available if you are a member of an organization using GitHub Team or GitHub Enterprise Cloud.
|
||||
|
||||
For more information, see "[GitHub Codespaces overview](https://docs.github.com/en/codespaces/overview)."
|
||||
|
||||
## Work on documentation in a codespace
|
||||
|
||||
The steps described below assume you have GitHub Codespaces set up to edit files using Visual Studio Code for Web. The steps are very similar if you have configured a different editor. For more information, see "[Setting your default editor for GitHub Codespaces](https://docs.github.com/en/codespaces/customizing-your-codespace/setting-your-default-editor-for-codespaces)."
|
||||
|
||||
1. Go to the `docs` repository: [https://github.com/github/docs](https://github.com/github/docs).
|
||||
1. If you're an open source contributor: [fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) to your own organization.
|
||||
1. [Create a branch to work on](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository).
|
||||
1. On the main page of the new `docs` repository, click the **Code** button and click **Create codespace on BRANCHNAME**.<br>
|
||||
The "Setting up your codespace" page is displayed. After a short time the browser-based version of Visual Studio Code is displayed.
|
||||
1. Use the Explorer to navigate to the markdown file you want to edit. This will be located below the `content` directory. <br>
|
||||
In most cases, the path to the file, below the `content` directory, matches the path in URL, minus the `.md` file name extension. For example, the source for the article <code>https<span></span>://docs.github.com/en/**codespaces/getting-started/quickstart**</code> is the markdown file <code>content/**codespaces/getting-started/quickstart**.md</code>.
|
||||
1. Edit the markdown file as required.
|
||||
1. Save your changes.
|
||||
1. Commit and push your changes, either using the "Source Control" view, or using Git commands from the Terminal. For more information, see "[About Git](https://docs.github.com/en/get-started/using-git/about-git)."
|
||||
1. Go to the **Pull requests** tab of the `github/docs` repository: https://github.com/github/docs/pulls
|
||||
1. Click **New pull request**.
|
||||
1. If you're an open source contributor: click **compare across forks** and choose the forked repository you created, and your working branch.<br>
|
||||
Otherwise: change the "compare" branch to your working branch.
|
||||
1. Check that the changes displayed include all of the changes you made in the codespace. If they do not, it indicates there are changes you have not pushed from the codespace to GitHub.
|
||||
1. Click **Create pull request**.
|
||||
1. Fill out the details for your pull request and click **Create pull request**.<br>
|
||||
Your pull request will be reviewed by a member of the GitHub documentation team.
|
||||
The content in the `contributing` directory has been deprecated. See "[Working on a GitHub Docs in a codepsace](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,343 +1 @@
|
||||
# Markup reference for GitHub Docs <!-- omit in toc -->
|
||||
|
||||
## Table of contents <!-- omit in toc -->
|
||||
- [Writing in Markdown](#writing-in-markdown)
|
||||
- [Lists](#lists)
|
||||
- [Usage](#usage)
|
||||
- [Callout tags](#callout-tags)
|
||||
- [Usage](#usage-1)
|
||||
- [Code sample annotations](#code-sample-annotations)
|
||||
- [Usage](#usage-2)
|
||||
- [Code sample syntax highlighting](#code-sample-syntax-highlighting)
|
||||
- [Usage](#usage-3)
|
||||
- [Octicons](#octicons)
|
||||
- [Usage](#usage-4)
|
||||
- [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)
|
||||
|
||||
## Writing in Markdown
|
||||
|
||||
[Markdown](http://daringfireball.net/projects/markdown/) is a human-friendly syntax for formatting plain text. Our documentation is written with [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/about-writing-and-formatting-on-github), a custom version of Markdown based on the [CommonMark specification](https://github.github.com/gfm/), and it is used across GitHub.
|
||||
|
||||
This site's Markdown rendering is powered by [`/lib/render-content`](/lib/render-content), which is in turn built on the [`remark`](https://remark.js.org/) Markdown processor.
|
||||
|
||||
## Lists
|
||||
|
||||
In a list item, the general rules for additional content after the first paragraph are:
|
||||
|
||||
* Images and subsequent paragraphs should each **be on their own line and separated by a blank line**.
|
||||
* All subsequent lines in a list item **must match up with the first text after the list marker**.
|
||||
|
||||
### Usage
|
||||
|
||||
For example, this is the correct way to write list items with multiple paragraphs or objects:
|
||||
|
||||
```markdown
|
||||
1. Under your repository name, click **Actions**.
|
||||
|
||||
|
||||
|
||||
This is another paragraph in the list.
|
||||
1. This is the next item.
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Callout tags
|
||||
|
||||
Callouts highlight important information that customers need to know. We use standard formatting and colors for different types of callouts: notes, warnings, and danger notices. Use tags before and after the text you’d like included in the callout box.
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
{% note %}
|
||||
|
||||
**Note:** Owners and administrators can add outside collaborators to a repository.
|
||||
|
||||
{% endnote %}
|
||||
```
|
||||
|
||||
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 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
|
||||
```
|
||||
|
||||
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**
|
||||
|
||||
You can also add a header that includes the name of the language and a button to copy the contents of the code block:
|
||||
|
||||
```javascript copy
|
||||
const copyMe = true
|
||||
```
|
||||
|
||||
## Octicons
|
||||
|
||||
Octicons are icons used across GitHub’s interface. We reference octicons when documenting the user interface and to indicate binary values in tables. Find the name of specific octicons on the [Octicons site](https://primer.style/octicons).
|
||||
|
||||
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 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.
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
{% octicon "<name of octicon>" %}
|
||||
{% octicon "plus" %}
|
||||
{% octicon "plus" aria-label="Add file" %}
|
||||
"{% octicon "plus" aria-hidden="true" %} Add file"
|
||||
```
|
||||
|
||||
## Operating system tags
|
||||
|
||||
We occasionally need to write documentation for different operating systems. Each operating system may require a different set of instructions. We use operating system tags to demarcate information for each operating system.
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
{% mac %}
|
||||
|
||||
These instructions are pertinent to Mac users.
|
||||
|
||||
{% endmac %}
|
||||
```
|
||||
|
||||
```
|
||||
{% windows %}
|
||||
|
||||
These instructions are pertinent to Windows users.
|
||||
|
||||
{% endwindows %}
|
||||
```
|
||||
|
||||
```
|
||||
{% linux %}
|
||||
|
||||
These instructions are pertinent to Linux users.
|
||||
|
||||
{% endlinux %}
|
||||
```
|
||||
|
||||
You can define a default platform in the frontmatter. For more information, see the [content README](../content/README.md#defaultplatform).
|
||||
|
||||
## Tool tags
|
||||
|
||||
We occasionally need to write documentation for different tools (GitHub UI, GitHub CLI, GitHub Desktop, cURL, Codespaces, Visual Studio Code, JetBrains IDEs, GitHub Enterprise Importer CLI, GraphQL API). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool.
|
||||
|
||||
On rare occasions, we will add new tools. Before adding a new tool, read the [tool switcher content model](./tool-switcher.md). To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](../lib/all-tools.js) as a key-value pair. The key is the tag you'll use to refer to the tool in the article, the value is how the tool will be identified on the tool picker at the top of the article.
|
||||
|
||||
You can define a default tool in the frontmatter. For more information, see the [content README](../content/README.md#defaulttool).
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
{% webui %}
|
||||
|
||||
These instructions are pertinent to GitHub UI users.
|
||||
|
||||
{% endwebui %}
|
||||
```
|
||||
|
||||
```
|
||||
{% cli %}
|
||||
|
||||
These instructions are pertinent to GitHub CLI users.
|
||||
|
||||
{% endcli %}
|
||||
```
|
||||
|
||||
```
|
||||
{% desktop %}
|
||||
|
||||
These instructions are pertinent to GitHub Desktop.
|
||||
|
||||
{% enddesktop %}
|
||||
```
|
||||
|
||||
```
|
||||
{% curl %}
|
||||
|
||||
These instructions are pertinent to cURL users.
|
||||
|
||||
{% endcurl %}
|
||||
```
|
||||
|
||||
```
|
||||
{% codespaces %}
|
||||
|
||||
These instructions are pertinent to Codespaces users. They are mostly used outside the Codespaces docset, when we want to refer to how to do something inside Codespaces. Otherwise `webui` or `vscode` may be used.
|
||||
|
||||
{% endcodespaces %}
|
||||
```
|
||||
|
||||
```
|
||||
{% vscode %}
|
||||
|
||||
These instructions are pertinent to VS Code users.
|
||||
|
||||
{% endvscode %}
|
||||
```
|
||||
|
||||
```
|
||||
{% jetbrains %}
|
||||
|
||||
These instructions are pertinent to users of JetBrains IDEs.
|
||||
|
||||
{% endjetbrains %}
|
||||
```
|
||||
|
||||
```
|
||||
{% importer_cli %}
|
||||
|
||||
These instructions are pertinent to GitHub Enterprise Importer CLI users.
|
||||
|
||||
{% endimporter_cli %}
|
||||
```
|
||||
|
||||
```
|
||||
{% api %}
|
||||
|
||||
These instructions are pertinent to API users.
|
||||
|
||||
{% endapi %}
|
||||
```
|
||||
|
||||
```
|
||||
{% powershell %}
|
||||
|
||||
These instructions are pertinent to `pwsh` and `powershell` commands.
|
||||
|
||||
{% endpowershell %}
|
||||
```
|
||||
|
||||
```
|
||||
{% bash %}
|
||||
|
||||
These instructions are pertinent to Bash shell commands.
|
||||
|
||||
{% endbash %}
|
||||
```
|
||||
|
||||
```
|
||||
{% javascript %}
|
||||
|
||||
These instructions are pertinent to javascript users.
|
||||
|
||||
{% endjavascript %}
|
||||
```
|
||||
|
||||
## Reusable and variable strings of text
|
||||
|
||||
Reusable strings (commonly called content references or conrefs) contain content that’s used in more than one place in our documentation and allow us to change the content in a single location rather than every place the string appears.
|
||||
|
||||
For longer strings, we use reusables, and for shorter strings, we use variables. For more information about reusables, see the [reusables README](../data/reusables/README.md). For more information about variables, see the [variables README](../data/variables/README.md).
|
||||
|
||||
## Table row headers
|
||||
|
||||
If you create a table where the first column contains headers for the table rows, wrap your table in the Liquid tag `{% rowheaders %} {% endrowheaders %}`. For more information, see "[Use proper markup for row and column headers](./content-style-guide.md#use-proper-markup-for-row-and-column-headers)" in the style guide.
|
||||
|
||||
### Example table with row headers
|
||||
|
||||
```
|
||||
{% rowheaders %}
|
||||
|
||||
| | Mona | Tom | Hobbes |
|
||||
|---|---|---|---|
|
||||
|Type of cat| Octo | Tuxedo | Tiger |
|
||||
|Likes to swim in the ocean| Yes | No | No |
|
||||
|
||||
{% endrowheaders %}
|
||||
```
|
||||
|
||||
### Example table without row headers
|
||||
|
||||
```
|
||||
| Name | Vocation |
|
||||
| --- | --- |
|
||||
| Mona | GitHub mascot |
|
||||
| Tom | Mouse antagonist |
|
||||
| Hobbes | Best friend |
|
||||
```
|
||||
|
||||
## Tables with codeblocks
|
||||
|
||||
Although using tables to contain block items, such as code blocks, is generally discouraged, occasionally it may be appropriate.
|
||||
|
||||
Because [tables in GitHub Flavored Markdown](https://github.github.com/gfm/#tables-extension-) cannot contain any line breaks or block-level structures, you must use HTML tags to write the table structure.
|
||||
|
||||
When HTML tables contain code blocks, the width of the table might exceed the regular width of page content, and then overflow into the area normally containing the mini table of contents.
|
||||
|
||||
If this happens, add the following CSS style to the `<table>` HTML tag:
|
||||
|
||||
```html
|
||||
<table style="table-layout: fixed;">
|
||||
```
|
||||
|
||||
For a current example of this usage, see the [GitHub Actions examples workflow library](https://docs.github.com/en/actions/examples).
|
||||
|
||||
## Internal links with AUTOTITLE
|
||||
|
||||
When linking to another GitHub docs page, use standard Markdown syntax like `[]()` but type `AUTOTITLE` instead of the page title. The application will replace `AUTOTITLE` with the title of the linked page during rendering. This special keyword is case-sensitive, so take care with your typing or the replacement will not work.
|
||||
|
||||
### Usage
|
||||
|
||||
- `For more information, see "[AUTOTITLE](/path/to/page)."`
|
||||
- `For more information, see "[AUTOTITLE](/path/to/page#section-link)."`
|
||||
- `For more information, see the TOOLNAME documentation in "[AUTOTITLE](/path/to/page?tool=TOOLNAME)."`
|
||||
|
||||
Note that **same-page section links do not work** with this keyword. Type out the full header text instead.
|
||||
|
||||
Read more about links in the [content style guide](./content-style-guide.md#links).
|
||||
The content in the `contributing` directory has been deprecated. See "[Using Markdown and Liquid in GitHub Docs](https://docs.github.com/en/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,584 +1 @@
|
||||
# Content model for GitHub Docs
|
||||
|
||||
**Note:** This version of the content model is no longer maintained and will be deprecated. See the [content model](https://docs.github.com/contributing/style-guide-and-content-model/content-model) on docs.github.com for the most up-to-date version. Open any pull requests against the `contributing/style-guide-and-content-model/content-model.md` file.
|
||||
|
||||
_Full TOC :arrow_upper_left:_
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Content structure](#content-structure)
|
||||
- [Content types](#content-types)
|
||||
- [Contents of a GitHub Docs article](#contents-of-a-github-docs-article)
|
||||
|
||||
## Introduction
|
||||
|
||||
This content model explains the goals of each type of content we create within GitHub Docs, and what to include when you're writing or updating an article. We use a model to ensure that our content consistently, clearly, and comprehensively communicates what people need to achieve their goals with GitHub quickly and easily.
|
||||
|
||||
We use these types across all documentation sets to provide a consistent user experience––any content type applies to any product or audience. Our content types evolve over time and we add new types as needed. We only publish content that follows the model.
|
||||
|
||||
Consistency helps people form mental models of the documentation and understand how to find the information they need as they return to GitHub Docs over time. It’s also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you're an open source contributor making your first commit or a GitHub writer documenting an entire new product.
|
||||
|
||||
## Content structure
|
||||
|
||||
Docs are organized into multiple levels of hierarchy on our site:
|
||||
|
||||
- Top-level doc set
|
||||
- Categories
|
||||
- Map topics
|
||||
- Articles
|
||||
|
||||
### Homepage content
|
||||
|
||||
The GitHub Docs homepage, [docs.github.com](https://docs.github.com/), highlights the most important topics that people want to find. We limit the number of doc sets on the homepage so that people can find information and the homepage does not become overcrowded and difficult to search.
|
||||
|
||||
The homepage includes all top-level doc sets and some categories. Content on the homepage is organized around GitHub concepts and practices. For example, the "CI/CD and DevOps" group includes top-level doc sets for GitHub Actions, GitHub Packages, and GitHub Pages.
|
||||
|
||||
#### Adding a doc set to the homepage
|
||||
|
||||
The goal of the homepage is to help people find information about the GitHub feature or product that they want to learn about. Every item on the homepage dilutes the discoverability of every other item, so we limit the number of doc sets included on the homepage.
|
||||
|
||||
If a new top-level doc set is created, it is added to the homepage.
|
||||
|
||||
If a category serves as the starting point for using a GitHub product or feature, it can be added to the homepage.
|
||||
|
||||
For example, under the "Security" grouping on the homepage, in addition to the "[Code security](https://docs.github.com/en/code-security)" top-level doc set, the "[Supply chain security](https://docs.github.com/en/code-security/supply-chain-security)," "[Security advisories](https://docs.github.com/en/code-security/security-advisories)," "[Dependabot](https://docs.github.com/en/code-security/dependabot)," "[Code scanning](https://docs.github.com/en/code-security/code-scanning)," and "[Secret scanning](https://docs.github.com/en/code-security/secret-scanning)" categories are included because each of those categories are the entry point to GitHub products and features. "[Security overview](https://docs.github.com/en/code-security/security-overview)" is not included on the homepage because it provides additional information for using code security products and is not an introduction to a product or feature.
|
||||
|
||||
### Top-level doc set
|
||||
|
||||
Top-level doc sets are organized around a GitHub product, feature, or core workflow. All top-level doc sets appear on the Docs homepage. You should only create a top-level doc set when there is a large amount of content to be contained in the new doc set, multiple categories that are broken down into map topics, and the topic applies across products, features, or account types. If the content could fit in any existing top-level doc set, it probably belongs in that existing doc set.
|
||||
- Top-level doc sets are of roughly equal importance to one another (each is centered on a GitHub product or major feature)
|
||||
- Most top-level doc sets have a landing page layout, unless there is a significant exception. For example, the "[Site policy](https://docs.github.com/en/site-policy)" doc set does not have guides or procedural articles like other doc sets, so it does not use a landing page layout.
|
||||
|
||||
#### Titles for top-level doc sets
|
||||
- Feature or product based.
|
||||
- Describes what part of GitHub someone is using.
|
||||
- Examples
|
||||
- [Organizations](https://docs.github.com/en/organizations)
|
||||
- [GitHub Issues](https://docs.github.com/en/issues)
|
||||
|
||||
### Category
|
||||
|
||||
Categories are usually organized around a feature or a discrete set of tasks within a top-level doc set, aligning with product themes. A category's subject isn't so broad that its contents are hard to manage or the category grows too large to use. Some categories appear on the Docs homepage.
|
||||
- Categories often start small and grow with the product.
|
||||
- Large categories may contain map topics to subdivide content around more specific user journeys or tasks.
|
||||
- Use long procedural articles to group related chunks of content and keep articles within the category streamlined.
|
||||
- When categories have more than ten articles, consider breaking the content into map topics or additional categories, unless there's a reason to keep all of the content together.
|
||||
|
||||
#### Titles for categories
|
||||
- Task-based (begins with a gerund)
|
||||
- Describes the big-picture purpose or goal of using the feature or product
|
||||
- General or high-level enough to scale with future product enhancements
|
||||
- Category titles must be 67 characters or shorter and have a [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) less than 27 characters
|
||||
- Examples
|
||||
- [Setting up and managing your GitHub user account](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account)
|
||||
- [Installing GitHub Enterprise](https://docs.github.com/en/enterprise-server@3.0/admin/installation)
|
||||
|
||||
#### Intros for categories
|
||||
All categories have intros. Keep the intros one sentence long, and general or high-level enough to scale with future product changes without having to remember to update the intro. If you significantly change a category’s structure, check its intro for needed updates.
|
||||
|
||||
### Map topic
|
||||
|
||||
Map topics introduce a section of a category, grouping articles within a category around more specific workflows or subjects that are part of the category’s larger task.
|
||||
|
||||
Map topics contain at least three articles. When map topics have more than eight articles, it may be useful to consider breaking the content into more specific map topics, unless there’s a reason to keep all of the information together.
|
||||
|
||||
#### Titles for map topics
|
||||
- Task-based (begins with a gerund)
|
||||
- Describes a more specific task within the larger workflow of the category it’s in
|
||||
- General or high-level enough to scale with future additions to the product
|
||||
- Map topic titles must be 63 characters or shorter and have a [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) less than 30 characters
|
||||
- Examples
|
||||
- [Understanding your software supply chain](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain)
|
||||
- [Managing users in your enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise)
|
||||
|
||||
#### Intros for map topics
|
||||
All map topics have intros. Keep the intros one sentence long, and general or high-level enough to scale with future product changes without having to remember to update the intro. If you add or remove articles in a map topic, check its intro for needed updates.
|
||||
|
||||
### Article
|
||||
|
||||
An article is the basic unit of content for GitHub Docs––while we use multiple content types, they're all published as articles. Each content type has its own purpose, format, and structure, yet we use standard elements in every article type, like intros, to ensure articles provide a consistent user experience.
|
||||
|
||||
### Content order
|
||||
|
||||
We organize content predictably within categories, map topics, and articles, from broadest applicability to most specific, narrow, or advanced, following this order:
|
||||
- Conceptual content
|
||||
- Referential content
|
||||
- Procedural content for enabling a feature or setting
|
||||
- Procedural content on using a feature
|
||||
- Procedural content on managing a feature or setting
|
||||
- Procedural content on disabling a feature or setting
|
||||
- Procedural content on destructive actions (e.g. deletion)
|
||||
- Troubleshooting information
|
||||
|
||||
### Titles
|
||||
|
||||
Titles fully describe what a page is about, and what a user will know by reading it.
|
||||
|
||||
Titles are challenging! Use these general guidelines to help create clear, helpful, and descriptive titles. See below for specific guidelines for each content type.
|
||||
|
||||
#### Titles for all content types
|
||||
- Titles clearly describe what a page is about. They are descriptive and specific.
|
||||
- Use: Browsing actions in the workflow editor
|
||||
- Use: Example of configuring a codespace
|
||||
- Avoid: Using the workflow editor sidebar
|
||||
- Avoid: Example
|
||||
- Titles have hard limits for length to keep them easy to understand (and easier to render on the site):
|
||||
- Category titles: 67 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 27 characters
|
||||
- Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 30 characters
|
||||
- Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 31 characters, ideally 20-25 characters
|
||||
- Titles are consistent across a content type
|
||||
- See specific guidelines for each content type
|
||||
- Titles aren’t repetitive––vary the verbs used for procedure or map topic titles when possible
|
||||
- Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products
|
||||
- Use: "GitHub's billing plans"
|
||||
- Avoid: "Billing plans for user and organization accounts"
|
||||
- Titles use consistent terminology
|
||||
- Develop and follow patterns within a category or on similar subjects
|
||||
- Titles use terminology from the product itself
|
||||
- Write the title and the intro at the same time
|
||||
- Use the intro to develop the ideas presented in the title
|
||||
- See guidance on intros for more information
|
||||
- If it's hard to come up with a title, consider the content type. Sometimes trouble choosing a title indicates that another content type would fit better.
|
||||
- Think about how the title will appear in search results for multiple products
|
||||
- What specific words do we need to include in the title or intro so that folks don’t mistake it for content about a different product?
|
||||
- Think about how the title will look in production
|
||||
|
||||
### Topics
|
||||
|
||||
Topics are used to filter articles and are searchable across the docs site. For some layouts, such as landing pages or guides, people can select which articles are displayed by filtering topics. Use these guidelines to help choose which topics to add to an article's frontmatter. For more information on adding topics to an article see, "[Topics](https://github.com/github/docs/tree/main/content#topics)" and for a list of all allowed topics, see [`allowed-topics`](https://github.com/github/docs/blob/main/data/allowed-topics.js).
|
||||
|
||||
#### Topics for all content types
|
||||
- All articles should have at least one topic
|
||||
- Use nouns as topics
|
||||
- Topics help people meaningfully group content
|
||||
- When possible, use more specific topics that are relevant and not just broad topics. For example, `REST` or `GraphQL` rather than just `API`
|
||||
- Ensure that topics on similar articles are consistent so that people who filter by a topic get all of the relevant articles. For example, all articles about CI should have the `CI` topic plus more specific topics
|
||||
- Avoid ambiguous topics. For example, `Actions` may not be a useful topic within the Actions product since it could refer to the product GitHub Actions or the product element called an action
|
||||
- Topics add value beyond and do not replicate the article’s title, type, or category
|
||||
- For example, within the Actions product, `Actions` does not add value since someone in this section of the docs would already know that they are looking at Actions docs
|
||||
- Use `Fundamentals` for articles related to the core concepts of a product area.
|
||||
- Use: `Fundamentals` in an article like “Introduction to GitHub Actions”
|
||||
- Avoid: `Actions` in an article like "Introduction to GitHub Actions"
|
||||
- Commonly-recognized abbreviations can be used, but obscure or ambiguous abbreviations should be avoided
|
||||
- Use: `CI` instead of `Continuous integration`
|
||||
- Avoid: `AS` instead of `Advanced Security`
|
||||
- Use the short forms of GitHub product names
|
||||
- Use: `Actions` instead of `GitHub Actions`
|
||||
|
||||
#### Checklist for choosing topics
|
||||
Consider these questions to help choose topics for an article. Not every article will have a topic for each item in the checklist.
|
||||
|
||||
- [ ] What is the feature or product area?
|
||||
- Example: `Enterprise`
|
||||
- [ ] Is the article about a sub-feature (unless the product name matches the feature name)?
|
||||
- Example: `Dependabot`
|
||||
- [ ] Is the feature part of a restricted program?
|
||||
- Example: `Advanced Security`
|
||||
- [ ] What element of the feature or product is the article?
|
||||
- Example: `Organizations`
|
||||
- [ ] What is the broad purpose of the article?
|
||||
- Example: `Permissions`
|
||||
- [ ] What programming languages, package managers, or ecosystems does the article explicitly address? (Note: only include these topics if it adds value to someone filtering the docs, not just if an article lists supported languages, package managers, or ecosystems.)
|
||||
- Example: `Ruby`
|
||||
|
||||
### Reusing content
|
||||
|
||||
We use reusable and variable strings to use the same chunk of content, such as a procedural step or a conceptual paragraph, in multiple places. We generally don't reuse large sections of articles without a specific reason. When an entire section of an article might be relevant in more than one article, take a look at the purpose of both. Is there an opportunity to create a single, long-form article? Refer to the content models to clarify the best permanent home for the information, and link to it from the other article.
|
||||
|
||||
## Content types
|
||||
|
||||
Any of these content types can be shared as an article on its own, and some content types can also be used as sections within a larger article.
|
||||
|
||||
### Conceptual
|
||||
|
||||
Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples. Conceptual content is clear enough for a novice audience but also includes relevant information for advanced users. People most often use conceptual content when they're learning.
|
||||
|
||||
We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article.
|
||||
|
||||
#### How to write conceptual content
|
||||
Use the [conceptual content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#conceptual) to write a conceptual article.
|
||||
|
||||
- Describe in plain language what the feature, product, or topic is
|
||||
- Describe its purpose and why it’s useful to the reader
|
||||
- Share use cases or examples
|
||||
- If relevant, describe how the feature or topic works (be mindful of audience and the right location for deep dives into technical details)
|
||||
- Highlight any details the reader needs to know to use the feature
|
||||
- Include next steps for getting started with the feature (whether through further reading links or content within the article itself)
|
||||
|
||||
#### Titles for conceptual content
|
||||
- Conceptual articles or headers of conceptual sections start with "About [subject]”
|
||||
- Use a noun to describe the subject
|
||||
- Use: "About code scanning"
|
||||
- Avoid: "About scanning your code for vulnerabilities"
|
||||
|
||||
#### Examples of conceptual content
|
||||
- Conceptual articles
|
||||
- [About GitHub Sponsors](https://docs.github.com/en/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors)
|
||||
- [About enterprise accounts](https://docs.github.com/en/github/setting-up-and-managing-your-enterprise/about-enterprise-accounts)
|
||||
- Conceptual sections within other articles
|
||||
- About security policies in [Adding a security policy to your repository](https://docs.github.com/en/code-security/security-advisories/adding-a-security-policy-to-your-repository)
|
||||
- About GitHub Enterprise licenses in [Managing your GitHub Enterprise Server license](https://docs.github.com/en/enterprise-server@latest/admin/overview/managing-your-github-enterprise-license)
|
||||
- About maintenance mode in [Enabling and scheduling maintenance mode](https://docs.github.com/en/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode)
|
||||
|
||||
### Referential
|
||||
|
||||
Referential content provides detailed information that people need while they're actively using a feature.
|
||||
|
||||
We create referential articles and referential sections within other articles.
|
||||
- Some major subjects may require their own referential article, especially if there is a large amount of referential content, such as for search syntax or YAML syntax in GitHub Actions.
|
||||
- For smaller amounts of content or more specific information, like a list of a feature’s supported languages or hardware requirements, use referential sections in context within procedural or conceptual articles.
|
||||
|
||||
#### How to write referential content
|
||||
Use the [referential content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#referential) to write a referential article.
|
||||
|
||||
- Write a sentence or an entire conceptual section to introduce the referential content
|
||||
- Present the actual referential content clearly and consistently
|
||||
- For subjects with a single element to explain, use a list
|
||||
- Example: [Navigating code on GitHub](https://docs.github.com/en/github/managing-files-in-a-repository/navigating-code-on-github)
|
||||
- For subjects with multiple elements to explain, use a table
|
||||
- Example: [Repository permission levels for an organization](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization)
|
||||
- For longer referential content, such as YAML syntax for workflows, use headers consistently:
|
||||
- H2 headers for each distinct section
|
||||
- H3 headers for subsections, such as examples
|
||||
- Example: [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)
|
||||
|
||||
#### Titles for referential content
|
||||
- Referential articles or headers of referential sections clearly describe the contents of the section, and generally begin with nouns
|
||||
- Titles include enough information to be accessible to novice users and fully describe the contents of each section
|
||||
- Titles avoid stacked nouns - use prepositions to break up long strings of nouns
|
||||
|
||||
#### Examples of referential content
|
||||
- Referential articles
|
||||
- [Keyboard shortcuts](hhttps://docs.github.com/en/github/getting-started-with-github/keyboard-shortcuts)
|
||||
- [Roles in an enterprise](https://docs.github.com/en/github/setting-up-and-managing-your-enterprise/roles-in-an-enterprise)
|
||||
- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)
|
||||
- [Billing](https://docs.github.com/en/rest/reference/billing) in the REST API documentation
|
||||
- [Mutations](https://docs.github.com/en/graphql/reference/mutations) in the GraphQL API documentation
|
||||
- Referential sections within other articles
|
||||
- Supported languages in [GitHub Mobile](https://docs.github.com/en/get-started/using-github/github-mobile#supported-languages-for-github-mobile)
|
||||
- Hardware considerations in [Installing GitHub Enterprise Server on AWS](https://docs.github.com/en/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)
|
||||
|
||||
### Procedural
|
||||
|
||||
Procedural content helps people complete a task from start to finish while they're using GitHub. Procedural content gives context on how the task fits into someone's larger journey.
|
||||
|
||||
We create procedural articles and procedural sections within larger articles.
|
||||
|
||||
#### How to write procedural articles
|
||||
Use the [procedural content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#procedural) to write a procedural article.
|
||||
|
||||
- Follow the [style guidelines for procedural steps](https://github.com/github/docs/blob/main/contributing/content-style-guide.md#procedural-steps).
|
||||
- Procedural content can get repetitive––look for opportunities to group related content into a single longer article.
|
||||
- Group multiple related procedures into a single article unless there's a reason not to.
|
||||
- If disabling a setting or undoing a task requires the same steps and has no special implications, do not write a separate procedure.
|
||||
- If disabling a setting or undoing a task requires different steps or has important or special implications, create a longer article to contain both procedures. Use an agnostic title.
|
||||
- Tell readers the expected outcome of the procedure.
|
||||
- Include troubleshooting tips as frequently as possible.
|
||||
|
||||
#### Titles for procedural content
|
||||
- Procedural articles or procedural sections within articles are task-based and begin with a gerund
|
||||
- Use: "Applying for a student developer pack"
|
||||
- Use active and specific verbs (brainstorm or use a thesaurus when needed)
|
||||
- Titles specifically describe the task contained within the article or header, but are general enough to reflect all of the content
|
||||
- Article title length: maximum 80 characters, 60 if possible
|
||||
|
||||
#### Examples of procedural content
|
||||
- [Adding information to your receipts](https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/adding-information-to-your-receipts)
|
||||
- [Inviting people to manage your enterprise account](https://docs.github.com/en/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise)
|
||||
- [Setting up continuous integration using workflow templates](https://docs.github.com/en/actions/guides/setting-up-continuous-integration-using-workflow-templates)
|
||||
|
||||
### Release notes
|
||||
|
||||
Release notes enable readers to understand and prepare for the customer-facing changes in each release of GitHub's versioned enterprise products (e.g., GitHub Enterprise Server). Good release notes provide administrators the necessary information to plan system upgrades in environments that require change control, and support end users who want to understand and prepare to use new GitHub features and functionality.
|
||||
|
||||
Writers source, edit, and publish release notes in collaboration with product DRIs, feature owners, and individual engineers at GitHub. For each individual release, we group release notes by predefined types.
|
||||
|
||||
We publish the release notes for [GitHub Enterprise Server](https://docs.github.com/enterprise-server/admin/release-notes) (GHES) and [GitHub AE](https://docs.github.com/github-ae@latest/admin/release-notes) (GHAE) on GitHub Docs, in the "Enterprise administrators" documentation set.
|
||||
|
||||
#### Types of releases
|
||||
|
||||
GitHub Docs provides release notes for feature releases of GHES and GHAE, and for patch releases of GHES. For more information about releases of each product, see "About upgrades to new releases" in the [GHES](https://docs.github.com/enterprise-server/admin/overview/about-upgrades-to-new-releases) or [GHAE](https://docs.github.com/github-ae@latest/admin/overview/about-upgrades-to-new-releases) documentation.
|
||||
|
||||
#### Guidance and example release notes
|
||||
|
||||
You can find guidance for the format, style, and tone of release notes, as well as examples of each type of note, in the [Content style guide for GitHub Docs](https://github.com/github/docs/blob/main/contributing/content-style-guide.md#release-notes).
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
Troubleshooting content includes built-in errors we expect users to encounter, common problems reported to support, and situations people might encounter while completing tasks. Use troubleshooting sections in guides or procedural articles to keep solutions close to procedures. Work with support and product managers to surface common errors and include them in the documentation.
|
||||
|
||||
#### Known issues
|
||||
Known issues are a subset of troubleshooting content specifically designed to respond to bugs, UX/UI issues, and other product quirks that generate a high volume of support tickets. Where troubleshooting content can describe errors that people *might* encounter, known issues explain problems that people *will* encounter.
|
||||
|
||||
Like all troubleshooting content, known issues can be a section in an article or a standalone article. If a known issue applies to a specific article, document it in that article. If a known issue applies to a specific set of articles or conceptual grouping of features, or if a product or feature has multiple known issues that should be grouped together, create a dedicated "Known issues with NAME" article.
|
||||
|
||||
Known issue content for a product or feature does not need to be comprehensive. Unlike other troubleshooting content, some known issues may not have workarounds. The goal of documenting an issue without a workaround is to help people confirm that the issue exists and save them time searching for a solution that doesn't exist yet after GitHub has already determined there isn't a workaround.
|
||||
|
||||
Product and feature owners (PMs and EMs) should help plan and review known issue content.
|
||||
|
||||
Use known issues to explain the following situations.
|
||||
|
||||
- Product behavior that regularly contradicts user expectations, but is not yet prioritized for remediation.
|
||||
- Behavior that regularly prevents the use of the product or feature for a common purpose.
|
||||
- Rare or severe bugs that GitHub has not yet prioritized fixing, and that are not explained in the product or by existing content on GitHub Docs.
|
||||
|
||||
#### How to write troubleshooting content
|
||||
- Use any GitHub Docs content type to create troubleshooting sections.
|
||||
- Whenever possible, keep troubleshooting content contained within procedural content or guides.
|
||||
- You can create a troubleshooting article when it makes sense to keep it separate, such as when there’s a large amount of troubleshooting content on a particular topic.
|
||||
- You can create a troubleshooting map topic if a product or feature has many troubleshooting articles, for example "[Troubleshooting SSH](https://docs.github.com/en/authentication/troubleshooting-ssh)."
|
||||
|
||||
#### Title guidelines for troubleshooting content
|
||||
- Troubleshooting FEATURE
|
||||
- Error: ERROR NAME
|
||||
- Known issues for PRODUCT
|
||||
|
||||
#### Examples of troubleshooting content
|
||||
- "[Troubleshooting SSH](https://docs.github.com/authentication/troubleshooting-ssh)"
|
||||
- "[Using GitHub Enterprise Server with a load balancer](https://docs.github.com/enterprise-server@latest/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#troubleshooting-connectivity-through-a-load-balancer)"
|
||||
- [Known issues](https://docs.github.com/enterprise-server@3.7/admin/release-notes#3.7.8-known-issues) in the GitHub Enterprise Server release notes
|
||||
- "[Error: We're doing an SSH key audit](https://docs.github.com/en/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit)"
|
||||
|
||||
### Combining multiple content types
|
||||
|
||||
Often, it's helpful to group information in context to help people complete a complex task, understand a set of related tasks, or illustrate an entire workflow. Use longer articles combining content types to ensure people find contextual content in the right place. Longer articles also help eliminate duplication of content and prepare content to scale as more options are added to the product. People most often need longer articles while actively using the product, and they may need to consult the article at different points on their journey.
|
||||
|
||||
#### How to combine multiple content types in an article
|
||||
- Use conceptual, procedural, referential, troubleshooting, or known issue content in a longer article, and do not use quickstart or tutorials
|
||||
- Use sections of different content types in the article as needed, and follow title guidelines for the content type
|
||||
- Most often, these articles will contain at least one procedural section plus at least one additional conceptual, referential, or procedural section
|
||||
- Use the content ordering guidelines to organize headers within the article.
|
||||
- Use troubleshooting information as frequently as possible.
|
||||
- You can replicate the article’s title in a header if needed
|
||||
|
||||
#### Title guidelines for articles that combine multiple content types
|
||||
- If there's a procedure within the article, use a task-based title that begins with a gerund
|
||||
- Titles are general enough to describe the range of information and tasks contained within the article
|
||||
- Titles describe the setting being toggled and are agnostic about what setting the reader chooses, e.g., "Setting repository visibility” instead of "Making a private repository public”
|
||||
|
||||
#### Examples of articles that combine multiple content types
|
||||
- [Setting repository visibility](https://docs.github.com/en/github/administering-a-repository/setting-repository-visibility)
|
||||
- [Enforcing repository management policies for organizations in your enterprise account](https://docs.github.com/en/github/setting-up-and-managing-your-enterprise/enforcing-repository-management-policies-in-your-enterprise-account)
|
||||
- [Upgrading your GitHub subscription](https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-your-github-subscription)
|
||||
- [Enabling and scheduling maintenance mode](https://docs.github.com/en/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode)
|
||||
|
||||
### Quickstart
|
||||
|
||||
Quickstarts enable a user to quickly complete a discrete, focused task by illustrating a workflow with only essential steps, in about five minutes or 600 words. Quickstarts can be used for quickly getting set up with a new tool, or for quickly completing another task. For more complex tasks, use a tutorial.
|
||||
|
||||
Quickstarts are useful when someone already understands the feature or product and is ready to try it out. Users of quickstarts are not looking for an explanation and don't need to be convinced to use the product––they just want instructions quickly. Users who don't understand a step are willing to dig deeper in a separate doc.
|
||||
|
||||
#### How to write a quickstart
|
||||
Use the [quickstart template](https://github.com/github/docs/blob/main/contributing/content-templates.md#quickstart) to create a quickstart guide.
|
||||
|
||||
Contents of quickstarts:
|
||||
- Introduction:
|
||||
- Highlights that this guide is quick and to-the-point by using phrasing like:
|
||||
- Quickly add [FEATURE] to your project
|
||||
- The essentials for getting started with [PRODUCT]
|
||||
- An abbreviated guide for people who are familiar with [FEATURE]
|
||||
- Clarifies audience
|
||||
- Clearly states prerequisites and prior knowledge needed
|
||||
- States what the user will accomplish or build
|
||||
- Procedural sections
|
||||
- Based on the quickstart's audience, the steps can be less explicit and formal than those used in procedural content. You do not have to use existing reusables to form these steps if the audience doesn’t require that level of detail.
|
||||
- Link out to other articles or resources rather than replicating them, to avoid interrupting the flow of information.
|
||||
- Give visual cues. Use code blocks and screenshots heavily to help reassure users that they're performing the correct actions.
|
||||
- Troubleshooting (optional)
|
||||
- In an ideal world, the guidance provided in a quick start will always work. If it exists, link out to any relevant troubleshooting content rather than including it in the document.
|
||||
- Next steps
|
||||
- Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps.
|
||||
- Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Skills.
|
||||
|
||||
#### Title guidelines for quickstarts
|
||||
- When the guide helps someone get started with a new tool, preface the title with "Quickstart", e.g. "Quickstart for GitHub Actions" or "Quickstart: Procedural title"
|
||||
- For other use cases, follow the title guidelines for procedures and omit the word "Quickstart"
|
||||
|
||||
#### Examples of quickstarts
|
||||
- [Quickstart for GitHub Actions](https://docs.github.com/en/actions/quickstart)
|
||||
- [Quickstart for GitHub Discussions](https://docs.github.com/en/discussions/quickstart)
|
||||
- [Quickstart for GitHub Educators](https://docs.github.com/en/education/quickstart)
|
||||
|
||||
### Tutorial
|
||||
|
||||
Tutorials help people learn about products and solve real world problems by guiding them through the entire workflow to complete a task. Tutorials are more conversational in tone than other content. A tutorial feels like a developer-to-developer conversation while remaining accessible to readers with varied technical knowledge. Products with tutorials must already have a quickstart. For bite-sized workflows, use the quickstart model instead.
|
||||
|
||||
Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem. Tutorials are for people who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help people who've implemented similar solutions in the past with other products use GitHub. Tutorials can also help people validate whether the solution is appropriate for their needs.
|
||||
|
||||
#### How to write a tutorial
|
||||
Use the [tutorial template](https://github.com/github/docs/blob/main/contributing/content-templates.md#tutorial) to create a tutorial.
|
||||
|
||||
Contents of tutorials:
|
||||
- Introduction
|
||||
- Clarifies audience
|
||||
- Clearly states prerequisites and prior knowledge needed
|
||||
- States what the user will accomplish or build
|
||||
- Includes an example of a successful project
|
||||
- Does not include the expected amount of time that it may take users to complete the task - this depends on the experience level of the user and can be demoralizing for beginners
|
||||
- Procedural sections
|
||||
- Based on the tutorial's audience, the steps can be less explicit and formal than those used in procedural content. You do not have to use existing reusables to form these steps if the audience doesn’t require that level of detail.
|
||||
- Use: "From your profile, click **Settings, and then click **Developer settings**.”
|
||||
- Avoid: In the upper-right corner of any page, click your profile photo, then click **Settings**. In the left sidebar, click **Developer settings**.
|
||||
- Link out to other articles or resources rather than replicating them, to avoid interrupting the flow of information in the tutorial.
|
||||
- Give visual cues. Use code blocks and screenshots heavily to help reassure users that they're performing the correct actions.
|
||||
- Provide real examples.
|
||||
- For example, don't tell a user to "Enter a commit message" - instead, give them an appropriate example commit message that matches the previous steps.
|
||||
- Troubleshooting
|
||||
- Acknowledge what may go wrong in the task and list a few common problems readers might run into with solutions.
|
||||
- Conclusion
|
||||
- Review what the user has accomplished or built. Refer back to the project provided in the introduction as an example of a successful project.
|
||||
- Next steps
|
||||
- Include 2-3 actionable next steps that the user take after completing the tutorial. Link off to other related information like:
|
||||
- Projects on GitHub that illustrate the introduced concepts
|
||||
- Relevant information on docs.github.com
|
||||
- Relevant GitHub Skills
|
||||
- Relevant published talks, blog posts, or Community Forum series posts by Hubbers
|
||||
|
||||
#### Title guidelines for tutorials
|
||||
- Follow the title guidelines for procedural articles
|
||||
- Don’t use "tutorial” or "guide” in the title
|
||||
|
||||
#### Examples of tutorials
|
||||
Tutorials:
|
||||
- [Adding labels to issues](https://docs.github.com/en/actions/guides/adding-labels-to-issues)
|
||||
- [Installing an Apple certificate on macOS runners for Xcode development](https://docs.github.com/en/actions/guides/installing-an-apple-certificate-on-macos-runners-for-xcode-development)
|
||||
|
||||
Language and framework guides:
|
||||
- [Building and testing Node.js](https://docs.github.com/en/actions/guides/building-and-testing-nodejs)
|
||||
- [Building and testing Python](https://docs.github.com/en/actions/guides/building-and-testing-python)
|
||||
- [Publishing Java packages with Maven](https://docs.github.com/en/actions/guides/publishing-java-packages-with-maven)
|
||||
|
||||
### Guides
|
||||
|
||||
We collectively refer to tutorials and quickstarts as "guides" across the site. On `/guides` landing pages, we include tutorials, quickstarts, and certain procedural articles in the list of guides for a doc set.
|
||||
|
||||
## Contents of a GitHub Docs article
|
||||
|
||||
Every article includes a few standard elements, and may include conditional or optional elements. We also use a standard order for content within an article. Check out the guidelines below for more details about each element.
|
||||
|
||||
Within an article, there is a standard order of content sections. Every article contains required elements. Articles will also contain conditional elements and optional elements outlined in content design or creation. See the guidelines below for more details.
|
||||
|
||||
1. Title
|
||||
2. Product callout (conditional)
|
||||
3. Intro
|
||||
4. Permissions statement (conditional)
|
||||
5. Tool switcher (conditional)
|
||||
6. Table of contents
|
||||
7. Conceptual content
|
||||
8. Referential content
|
||||
9. Prerequisites
|
||||
10. Procedural content
|
||||
11. Troubleshooting content
|
||||
12. Further reading (conditional)
|
||||
|
||||
Here's what some of these elements look like rendered in an article.
|
||||
|
||||
|
||||
|
||||
### Product callout
|
||||
|
||||
Use the product callout when a feature is available in specific products only and that availability cannot be conveyed by versioning alone. For example, if a feature is available for GHEC, GHES, and GHAE, you can version content about the feature for GHEC, GHES, and GHAE only. If a feature is available for Pro, Team, GHEC, GHES, and GHAE (but not Free), use a product callout to convey that availability.
|
||||
|
||||
All product callouts are stored as reusables in [`gated-features`](https://github.com/github/docs/tree/main/data/reusables/gated-features) and added in YAML frontmatter for relevant articles.
|
||||
|
||||
#### How to write a product callout
|
||||
- Product callouts follow a strict format, clearly identifying the feature and which products it’s available in.
|
||||
- Product callouts also include a link to "GitHub’s products” and occasionally to another relevant article.
|
||||
- Examples:
|
||||
- [Feature name] is available in [product(s)]. For more information, see "GitHub’s products.”
|
||||
- [Feature name] is available in public repositories with [free product(s), and in public and private repositories with [paid products]. For more information, see "GitHub’s products.”
|
||||
|
||||
#### Examples of articles with product callouts
|
||||
Check the source files and `gated-features` to see how source content is written.
|
||||
- [Roles in an enterprise](https://docs.github.com/en/github/setting-up-and-managing-your-enterprise/roles-in-an-enterprise)
|
||||
- [Managing a branch protection rule](https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule)
|
||||
- [Managing team synchronization for an organization](https://docs.github.com/en/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)
|
||||
|
||||
### Intro
|
||||
|
||||
The top of every page has an intro that provides context and sets expectations, allowing readers to quickly decide if the page is relevant to them. Intros also are displayed in search results to provide contextual information to help readers choose a result.
|
||||
|
||||
#### How to write an intro
|
||||
- Article intros are one to two sentences long.
|
||||
- Map topic and category intros are one sentence long.
|
||||
- API reference intros are one sentence long.
|
||||
- The intro for an API page should define the feature so that a user knows whether the feature meets their needs without reading the entire article.
|
||||
- Intros contain a high-level summary of the page’s content, developing the idea presented in a title with more detail.
|
||||
- Use approachable synonyms of words in the page’s title to help readers understand the article’s purpose differently. Avoid repeating words from the title when possible.
|
||||
- Intros are relatively evergreen and high-level, so they can scale with future changes to the content on the page without needing to be frequently updated.
|
||||
- For searchability, include keywords on the page's subject in the intro.
|
||||
- When a term in the intro has an acronym we’ll use elsewhere in the article, indicate the acronym.
|
||||
- Intros generally don't contain permissions for any tasks contained within the article.
|
||||
|
||||
### Permissions statements
|
||||
|
||||
Every procedure includes a permissions statement explaining the role required to take the action described in the procedure, which helps people understand whether they'll be able to complete the task.
|
||||
|
||||
Occasionally, it's relevant to mention required permissions in conceptual content, especially in standalone conceptual articles. Make sure to also include a permissions statement in related procedures (or write a longer article combining all of the content).
|
||||
|
||||
#### How to write a permissions statement
|
||||
- When a single set of permissions applies to all procedures in an article, use the [permissions frontmatter](https://github.com/github/docs/tree/main/content#permissions).
|
||||
- When an article contains multiple procedures and different permissions apply, include a separate permissions statement under each relevant header, before each procedure.
|
||||
- Don't include permissions in an article’s intro.
|
||||
- Roles exist at different levels. Refer only to the role at the same level as the action. For example, you need admin access to a repository (repository-level role) to configure protected branches. You can get admin access to a repository by being an organization owner (organization-level role), but the repository-level role is what actually governs your ability to take the action, so that is the only role that should be mentioned in the permissions statement.
|
||||
- Language to use in a permissions statement:
|
||||
- [ACCOUNT ROLE] can [ACTION].
|
||||
- People with [FEATURE ROLE] access for a [FEATURE] can [ACTION].
|
||||
- AVOID: [ACCOUNT ROLE] and people with [FEATURE ROLE] access for a [FEATURE] can [ACTION].
|
||||
|
||||
#### Examples of permissions statements
|
||||
- Article with separate permissions statements for each procedure: [Upgrading your GitHub subscription](https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-your-github-subscription)
|
||||
- Article with single permissions statement for multiple procedures: [Enforcing repository management policies in your enterprise account](https://docs.github.com/en/github/setting-up-and-managing-your-enterprise/enforcing-repository-management-policies-in-your-enterprise-account)
|
||||
|
||||
### Tool switcher
|
||||
|
||||
Some articles have content that varies depending on what tool someone uses to complete a task, such as the GitHub CLI or GitHub Desktop. For most content, the same conceptual or procedural information will be accurate for multiple tools. However, if the only way to make information clear and accurate is by distinguishing content by tool, use the tool switcher. Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts change based on what tool someone uses. For more information on using the tool switcher, see the [tool switcher content model](./tool-switcher.md).
|
||||
|
||||
### Table of contents
|
||||
Tables of contents are automatically generated. For more information see "[Autogenerated mini-TOCs](https://github.com/github/docs/tree/main/content#autogenerated-mini-tocs)."
|
||||
|
||||
### Conceptual content
|
||||
Conceptual content helps people understand or learn about a topic. See "[Conceptual](#conceptual)" above.
|
||||
|
||||
### Referential content
|
||||
Referential content provides structured information related to actively using a product or feature. See "[Referential](#referential)" above.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Prerequisites are information that people need to know before proceeding with a procedure, so that they can prepare everything they need before starting the task.
|
||||
|
||||
#### How to write prerequisites
|
||||
- Write prerequisites immediately before a procedure's numbered steps.
|
||||
- You can use a list, a sentence, or a paragraph to explain prerequisites.
|
||||
- You can also use a separate prerequisites section when:
|
||||
- The prerequisite information is very important and should not be missed.
|
||||
- There's more than one prerequisite.
|
||||
- To repeat or highlight important information about data loss or destructive actions, you may also use a warning or danger callout to share a prerequisite.
|
||||
|
||||
#### Title guidelines for prerequisites
|
||||
- When using a separate section, use a header called `Prerequisites`
|
||||
|
||||
#### Examples of articles with prerequisites sections
|
||||
- [Installing GitHub Enterprise Server on AWS](https://docs.github.com/en/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)
|
||||
- [Enabling subdomain isolation](https://docs.github.com/en/enterprise-server@latest/admin/configuration/enabling-subdomain-isolation)
|
||||
|
||||
### Procedural content
|
||||
Procedural content helps people complete tasks. See "[Procedural](#procedural)" above.
|
||||
|
||||
### Troubleshooting content
|
||||
|
||||
Troubleshooting content helps people avoid or work through errors. See "[Troubleshooting](#troubleshooting)" above.
|
||||
|
||||
### Further reading
|
||||
|
||||
Further reading sections highlight additional targeted articles that aren’t already included within the article’s content or sidebar. Use further reading sections sparingly when they provide real value.
|
||||
|
||||
#### How to write a further reading section
|
||||
- Use a bulleted list.
|
||||
- Use further reading sections sparingly and when they provide high value - see style guide for guidelines on linking.
|
||||
|
||||
#### Title and format for further reading sections
|
||||
```
|
||||
### Further reading
|
||||
- "[Article title](article-URL)”
|
||||
- [External resource title](external-resource-URL) in External Resource Name
|
||||
```
|
||||
The content in the `contributing` directory has been deprecated. See "[Style guide and content model](https://docs.github.com/en/contributing/style-guide-and-content-model)" in the GitHub Docs for the maintained version of this content.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,339 +1 @@
|
||||
# Templates for GitHub Docs content
|
||||
|
||||
You can copy any of these templates into a new Markdown file as the first step in creating a new article and opening a pull request.
|
||||
|
||||
- [Conceptual](#conceptual)
|
||||
- [Referential](#referential)
|
||||
- [Procedural](#procedural)
|
||||
- [Quickstart](#quickstart)
|
||||
- [Tutorial](#tutorial)
|
||||
- [Language guide for GitHub Actions](#language-guide-for-github-actions)
|
||||
|
||||
## Conceptual
|
||||
|
||||
Use the [content model](/contributing/content-model.md#conceptual) for full instructions and examples on how to write conceptual content.
|
||||
|
||||
```
|
||||
---
|
||||
title: About [subject]
|
||||
shortTitle: [subject] # Max 31 characters
|
||||
intro: 'Article intro. See tips for a great intro below.'
|
||||
product: '{{ optional product callout }}'
|
||||
type: overview
|
||||
topics: # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
|
||||
- [topic]
|
||||
versions:
|
||||
---
|
||||
|
||||
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#conceptual to write this article.-- >
|
||||
<!-- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://github.com/github/docs/blob/main/contributing/content-model.md#intro. -->
|
||||
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
|
||||
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#versions.-->
|
||||
<!-- Remove these comments from your article file when you're done writing. -->
|
||||
|
||||
## A section here
|
||||
|
||||
<!-- Write one or two paragraphs about the main idea of your topic, as a summary. -->
|
||||
<!-- Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our TOC. -->
|
||||
|
||||
## Another section here
|
||||
|
||||
<!-- Write one or two paragraphs about another element of your topic. -->
|
||||
<!-- Keep adding headers and sections until you've completed your article. -->
|
||||
|
||||
## Further reading
|
||||
|
||||
<!-- Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -->
|
||||
|
||||
- "[Article title](article-URL)"
|
||||
```
|
||||
|
||||
## Referential
|
||||
|
||||
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#referential) for full instructions and examples on how to write referential content.
|
||||
|
||||
```
|
||||
---
|
||||
title: Nouns describing your subject
|
||||
shortTitle: [subject] # Max 31 characters
|
||||
intro: 'Article intro. See tips for a great intro below.'
|
||||
product: '{{ optional product callout }}'
|
||||
type: reference
|
||||
topics: # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
|
||||
- [topic]
|
||||
versions:
|
||||
---
|
||||
|
||||
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#referential to write this article.-- >
|
||||
<!-- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://github.com/github/docs/blob/main/contributing/content-model.md#intro. -->
|
||||
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
|
||||
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#versions.-->
|
||||
<!-- Remove these comments from your article file when you're done writing -->
|
||||
|
||||
## A section here
|
||||
|
||||
<!-- Write one or two paragraphs about the main idea of your topic, as a summary. -->
|
||||
<!-- Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our TOC. -->
|
||||
|
||||
## Another section here
|
||||
|
||||
<!-- Write one or two paragraphs about another element of your topic. -->
|
||||
<!-- Keep adding headers and sections until you've completed your article. -->
|
||||
|
||||
## Further reading
|
||||
|
||||
<!-- Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -->
|
||||
|
||||
- "[Article title](article-URL)"
|
||||
```
|
||||
|
||||
## Procedural
|
||||
|
||||
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#procedural) for full instructions and examples on how to write procedural content.
|
||||
|
||||
```
|
||||
---
|
||||
title: Start with a gerund
|
||||
shortTitle: [subject] # Max 31 characters
|
||||
intro: 'Article intro. See tips for a great intro below.'
|
||||
product: '{{ optional product callout }}'
|
||||
type: how_to
|
||||
topics: # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
|
||||
- [topic]
|
||||
versions:
|
||||
---
|
||||
|
||||
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#procedural to write this article.-- >
|
||||
<!-- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://github.com/github/docs/blob/main/contributing/content-model.md#intro. -->
|
||||
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
|
||||
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#versions.-->
|
||||
<!-- Remove these comments from your article file when you're done writing -->
|
||||
|
||||
## Procedural section header here
|
||||
|
||||
<!-- Include prerequisite information or specific permissions information here. -->
|
||||
<!-- Then write procedural steps following the instructions in https://github.com/github/docs/blob/main/contributing/content-model.md#procedural-steps. -->
|
||||
<!-- Check if there's already a reusable string for the step you want to write in https://github.com/github/docs/tree/main/data/reusables. Tip: Look at the source file for a procedure located in the same area of the user interface to find reusables. -->
|
||||
|
||||
## Optionally, another procedural section here
|
||||
|
||||
<!-- Keep adding procedures until you've finished writing your article. -->
|
||||
|
||||
## Further reading
|
||||
|
||||
<!-- Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -->
|
||||
|
||||
- "[Article title](article-URL)"
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
|
||||
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#quickstart) for full instructions and examples on how to write quickstarts.
|
||||
|
||||
```
|
||||
---
|
||||
title: Quickstart title
|
||||
shortTitle: [subject] # Max 31 characters
|
||||
intro: 'Article intro. Highlight that the guide is quick and to the point.'
|
||||
type: quick_start
|
||||
topics: # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
|
||||
- [topic]
|
||||
versions:
|
||||
---
|
||||
|
||||
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#quickstart to write this article.-->
|
||||
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#versions.-->
|
||||
<!-- The entire quickstart should be about 600 words long or take about five minutes to read.-->
|
||||
<!-- Remove these comments from your article file when you're done writing -->
|
||||
|
||||
## Introduction
|
||||
|
||||
<!-- Build on the quick phrasing above by:
|
||||
- Clarifying the audience
|
||||
- Clearly stating prerequisites and prior knowledge needed
|
||||
- Stating what the user will accomplish or build-->
|
||||
|
||||
## Step one: Action the user will take
|
||||
|
||||
<!-- In one sentence, describe what the user will do in this step -->
|
||||
<!-- Steps should break down the tasks the user will complete in sequential order -->
|
||||
<!-- Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -->
|
||||
|
||||
### Task chunk
|
||||
|
||||
<!-- A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -->
|
||||
<!-- An example might be creating a personal access token for the action to use and then storing it in secrets -->
|
||||
<!-- For UI based tasks, include the button or options the users should click -->
|
||||
<!-- If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) -->
|
||||
|
||||
### Another task chunk
|
||||
|
||||
<!-- remove all of these comments when you're done -->
|
||||
|
||||
## Step 2: Do the next thing
|
||||
|
||||
<!-- Rinse and repeat, adding steps and tasks until the tutorial is complete -->
|
||||
|
||||
## Next steps
|
||||
|
||||
<!-- Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps. Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Skills. -->
|
||||
```
|
||||
|
||||
## Tutorial
|
||||
|
||||
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#tutorial) for full instructions and examples on how to write tutorials.
|
||||
|
||||
```
|
||||
---
|
||||
title: Tutorial title
|
||||
shortTitle: [subject] # Max 31 characters
|
||||
intro: 'Article intro. See tips for a great intro below'
|
||||
product: '{{ optional product callout }}'
|
||||
type: tutorial
|
||||
topics: # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
|
||||
- [topic]
|
||||
versions:
|
||||
---
|
||||
|
||||
<!-- Follow the instructions in https://github.com/github/docs/blob/main/contributing/content-model.md#quickstart to write this article.-->
|
||||
<!-- Great intros clarify who the tutorial is intended for, state what the user will accomplish, and state the technologies that will be used.-->
|
||||
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
|
||||
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#versions.-->
|
||||
<!-- Remove these comments from your article file when you're done writing -->
|
||||
|
||||
## Introduction
|
||||
|
||||
<!-- The tutorial introduction should include the following in a short paragraph:
|
||||
|
||||
- Clarify audience
|
||||
- State prerequisites and prior knowledge needed
|
||||
- State what the user will accomplish or build and the user problem it solves
|
||||
- Link to an example of the project the user will complete -->
|
||||
|
||||
## Step 1: Action the user will take
|
||||
|
||||
<!-- In one sentence, describe what the user will do in this step -->
|
||||
<!-- Steps should break down the tasks the user will complete in sequential order -->
|
||||
<!-- Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -->
|
||||
|
||||
### Task chunk
|
||||
|
||||
<!-- A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -->
|
||||
<!-- An example might be creating a personal access token for the action to use and then storing it in secrets -->
|
||||
<!-- For UI based tasks, include the button or options the users should click -->
|
||||
<!-- If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) -->
|
||||
|
||||
### Another task chunk
|
||||
|
||||
<!-- remove all of these comments when you're done -->
|
||||
|
||||
## Step 2: Do the next thing
|
||||
|
||||
<!-- Rinse and repeat, adding steps and tasks until the tutorial is complete
|
||||
|
||||
<!-- remember to show code snippets in context -->
|
||||
|
||||
<!-- ```yaml
|
||||
on:
|
||||
schedule:
|
||||
- cron: "40 19 * * *"
|
||||
``` -->
|
||||
|
||||
## Further reading
|
||||
|
||||
<!-- include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial -->
|
||||
|
||||
- "[Article title](article-URL)"
|
||||
```
|
||||
|
||||
## Language guides for GitHub Actions
|
||||
|
||||
Use the [tutorial content model](hhttps://github.com/github/docs/blob/main/contributing/content-model.md#tutorial) for full instructions and examples on how to language and framework guides for GitHub Actions.
|
||||
|
||||
```
|
||||
---
|
||||
title: Guide title
|
||||
shortTitle: [subject] # Max 31 characters
|
||||
intro: 'Article intro. See tips for a great intro below'
|
||||
product: '{{ site.data.reusables.gated-features.actions }}'
|
||||
type: tutorial
|
||||
topics: # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
|
||||
- [topic]
|
||||
versions:
|
||||
---
|
||||
|
||||
<!--
|
||||
- Great intros clarify who the guide is intended for, state what the user will accomplish, and state the technologies that will be used.
|
||||
- Intros are typically 1-3 sentence summaries, with a longer "Introduction" section that follows.
|
||||
- Remove these comments from your article file when you're done writing
|
||||
-->
|
||||
|
||||
## Introduction
|
||||
|
||||
<!--
|
||||
The language guide introduction should include the following in a short paragraph:
|
||||
- Clarify audience.
|
||||
- State prerequisites and prior knowledge needed.
|
||||
- Should the user have read any other articles?
|
||||
- State what the user will accomplish or build and the user problem it solves.
|
||||
-->
|
||||
|
||||
## Starting with the <language> workflow template
|
||||
|
||||
<!--
|
||||
Language guides typically walk through and build upon a starter workflow template. If that format doesn't work, you can include a boilerplate workflow.
|
||||
- Link to the GitHub Actions CI starter workflow as the boilerplate reference code and then walk through and build on that code in this guide: https://github.com/actions/starter-workflows/tree/master/ci
|
||||
- Provide instructions for adding the starter workflow template to a repository.
|
||||
- Include the starter template workflow code.
|
||||
-->
|
||||
|
||||
## Running on different operating systems
|
||||
|
||||
<!--
|
||||
Include a brief overview of how to choose the runner environment. These should be alternatives to what operating system is presented in the starter workflow/boilerplate template.
|
||||
-->
|
||||
|
||||
## Configuring the <language> version
|
||||
<!--
|
||||
- Describe when and how to use available setup actions that configure the version of the language on the runner (ex. actions/setup-node).
|
||||
- How does the setup action configure the version and what happens when the version isn't supported in the environment. What is the default version, when no version is configured.
|
||||
- Include any additional features the setup action might provide that are useful to CI.
|
||||
- If applicable, provide examples of configuring exact versions or major/minor versions.
|
||||
- Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project.
|
||||
- Provide examples of configuring matrix strategies.
|
||||
- Link out to any docs about available software on the GitHub-hosted runners. (Ex. https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners).
|
||||
- Include code samples.
|
||||
-->
|
||||
|
||||
## Installing dependencies
|
||||
|
||||
<!--
|
||||
- Include example of installing dependencies to prepare for building and testing.
|
||||
- Are there any dependencies or scenarios where people might need to install packages globally?
|
||||
- Include examples of common package managers.
|
||||
- If the language is supported by GitHub Packages, include an example installing dependencies from GitHub.
|
||||
- Include code samples.
|
||||
-->
|
||||
|
||||
## Caching dependencies
|
||||
|
||||
<!--
|
||||
Include an example of restoring cached dependencies. We'll want to link out to the article about caching for more information (https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows).
|
||||
-->
|
||||
|
||||
## Building your code
|
||||
|
||||
<!--
|
||||
- Include any compile steps.
|
||||
- Include any test commands.
|
||||
- Note that you can use the same commands that your repository needs to build and test your code by simply replacing the commands in the `run` keyword.
|
||||
- Include any basic examples or commands specific to test frameworks.
|
||||
- Include any common databases or services that might be needed. If so, we can link out to the services guides in the docs (https://docs.github.com/en/actions/configuring-and-managing-workflows/using-databases-and-service-containers).
|
||||
-->
|
||||
|
||||
## Packaging workflow data as artifacts
|
||||
|
||||
<!--
|
||||
This section can simply link out to https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts or provide additional information about which artifacts might be typical to upload for a CI workflow.
|
||||
-->
|
||||
```
|
||||
The content in the `contributing` directory has been deprecated. See "[Templates](https://docs.github.com/en/contributing/writing-for-github-docs/templates)" in the GitHub Docs for the maintained version of this content.
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# GitHub Partners
|
||||
|
||||
This folder contains templates to be used by GitHub's technology partners when contributing documentation, such as guides.
|
||||
|
||||
To get started, please [open an issue using this link](https://github.com/github/docs/issues/new?template=partner-contributed-documentation.md).
|
||||
|
||||
## Templates
|
||||
|
||||
### Tutorial template
|
||||
Tutorials guide the reader through an entire workflow to complete a task.
|
||||
|
||||
You should consider creating a tutorial when:
|
||||
|
||||
- The user has a basic understanding of the product and is interested in extending their use and understanding to solve a specific problem.
|
||||
- The user is looking for expert advice and a detailed discussion on best practices related their problem.
|
||||
- The user may have implemented a similar solution in the past using a different product.
|
||||
- The user wants to validate whether the solution is appropriate for their needs.
|
||||
|
||||
Get started with the tutorial template [here](/contributing/content-templates.md#tutorial).
|
||||
@@ -1,7 +1 @@
|
||||
### Labels
|
||||
Labels can help you find an issue you'd like to help with.
|
||||
- The [`help wanted` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) is for problems or updates that anyone in the community can start working on.
|
||||
- The [`good first issue` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) is for problems or updates we think are ideal for beginners.
|
||||
- The [`content` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) is for problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown.
|
||||
- The [`engineering` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) is for problems or updates in the docs.github.com website. These will usually require some knowledge of JavaScript/Node.js or YAML to fix.
|
||||
- Labels such as [`codespaces` label](https://github.com/github/docs/labels/codespaces), [`desktop` label](https://github.com/github/docs/labels/desktop), [`graphql` label](https://github.com/github/docs/labels/graphql) are used for filtering products and docs areas.
|
||||
The content in the `contributing` directory has been deprecated. See "[Label reference](https://docs.github.com/en/contributing/collaborating-on-github-docs/label-reference)" in the GitHub Docs for the maintained version of this content.
|
||||
|
||||
@@ -1,222 +1 @@
|
||||
# Creating and updating screenshots
|
||||
|
||||
Screenshots complement text instructions for using GitHub.
|
||||
|
||||
**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.
|
||||
- The interface has multiple competing choices that can cause confusion.
|
||||
|
||||
Don't use screenshots for simple steps where text does the job, or to show code commands or outputs.
|
||||
|
||||
## Examples of screenshots that meet and don't meet criteria
|
||||
|
||||
<details>
|
||||
|
||||
<summary>✅ Screenshots to include</summary>
|
||||
|
||||
- [The UI element is small or visually subtle](#the-ui-element-is-small-or-visually-subtle)
|
||||
- [The UI element is not immediately visible](#the-ui-element-is-not-immediately-visible)
|
||||
- [The interface has multiple choices that can cause confusion](#the-interface-has-multiple-choices-that-can-cause-confusion)
|
||||
|
||||
### The UI element is small or visually subtle
|
||||
|
||||
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.
|
||||
|
||||
As a bonus, the screenshot gives a visual reference for the aspect ratio required.
|
||||
|
||||
|
||||
|
||||
### The UI element is not immediately visible
|
||||
|
||||
Options to clone a gist are contained under a dropdown menu labeled "Embed."
|
||||
|
||||
The screenshot is helpful to locate the correct option in the menu, which is not visible until the dropdown is opened.
|
||||
|
||||
|
||||
|
||||
### The interface has multiple choices that can cause confusion
|
||||
|
||||
There are fully three settings options on a repository page: the repository settings menu itself, the floating gear icon by "About" to edit repository info, and the account settings accessed via the profile picture.
|
||||
|
||||
The screenshot is helpful to find the correct option.
|
||||
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>❌ Screenshots to omit</summary>
|
||||
|
||||
- [The UI element is easy to find](#the-ui-element-is-easy-to-find)
|
||||
- [The UI has few, straightforward choices](#the-ui-has-few-straightforward-choices)
|
||||
|
||||
### The UI element is easy to find
|
||||
|
||||
GitHub's "Create repository" button is visually prominent through size, color, and placement. There are few duelling choices.
|
||||
|
||||
Text instructions are adequate to help the user complete the step.
|
||||
|
||||
|
||||
|
||||
### The UI has few, straightforward choices
|
||||
|
||||
Simple and straightforward options, such as checking or unchecking a box, do not need a visual support.
|
||||
|
||||
Text instructions are adequate to help the user complete the step.
|
||||
|
||||
There are also two accessibility implications of including the full sentence of text below the checkbox in the screenshot:
|
||||
|
||||
1. It's hard to read for low-sighted users because it's small and not as crisp as HTML text.
|
||||
2. A person using a screen reader won't have access to the information, because it will not fit within alt text character limits. Including the text in the instructions would remedy this, but be unnecessarily wordy.
|
||||
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## Pros and cons of screenshots
|
||||
|
||||
Consider these factors when planning the screenshot strategy for an article or set of content.
|
||||
|
||||
### Pros of screenshots
|
||||
|
||||
- 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.
|
||||
|
||||
### Cons of screenshots
|
||||
|
||||
- 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
|
||||
- Static images only
|
||||
- 144 dpi
|
||||
- 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 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.
|
||||
- **Reduce negative space**, for example in input fields, by resizing your browser window until optimal.
|
||||
- Show interfaces in **light theme** wherever possible.
|
||||
- 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.
|
||||
- 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**.
|
||||
|
||||
|
||||
|
||||
#### 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:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
## Adding highlighting in Snagit
|
||||
|
||||
Use [Snagit](https://www.techsmith.com/screen-capture.html) to apply a contrasting stroke around the UI element being discussed.
|
||||
|
||||
The stroke is GitHub Primer color `fg.severe` (HEX #BC4C00 or RGB 188, 76, 0). This dark orange has good color contrast on both white and black. To check contrast on other background colors, use the [Color Contrast Analyzer](https://www.tpgi.com/color-contrast-checker/).
|
||||
|
||||
|
||||
|
||||
### Importing the GitHub Docs theme into Snagit
|
||||
|
||||
1. Download [`snagit-theme-github-docs.snagtheme`](./images/snagit-theme-github-docs.snagtheme) to your computer. Select the **Raw** tab, right-click the page, select "**Save as**," and save the file.
|
||||
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 dark orange rectangle to add it to your favorites.
|
||||
|
||||
### Adding a highlight to a screenshot
|
||||
|
||||
1. Open a screenshot in Snagit.
|
||||
2. Open the "**Resize image**" dialog below the image canvas to set pixel depth (resolution) and pixel width. On Windows, you may need to select **Advanced** to change the resolution. Ensure **Use resampling** is off.
|
||||
- pixel depth: 144dpi (equivalent to "2x" on Snagit for Mac)
|
||||
- pixel width: 1000 pixels maximum
|
||||
3. With the GitHub Docs theme open in the Shapes sidebar, select the dark orange rectangle.
|
||||
4. Drag and drop across the image to create a rectangle. Adjust height and width by dragging edges. Do not adjust the corner rounding, which should remain 4 px.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### 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).
|
||||
- `/assets/images/enterprise/enterprise-server`: Images that are applicable to _all_ releases of GitHub Enterprise Server or are applicable to the current release and future releases.
|
||||
- `/assets/images/enterprise/<release number>`: Ex: `/assets/images/enterprise/3.0/`. When an image is changed in a new GitHub Enterprise Server release, add the new image and move the old image to the directory corresponding to the last release that it should be displayed in.
|
||||
- `/assets/images`: Images that apply to the Free, Pro, Team plan or images that are not specific to any Enterprise plan.
|
||||
|
||||
### Example: An image differs between free-pro-team and all Enterprise plans
|
||||
|
||||
When there are slight or even drastic differences between the free-pro-team image and the associated Enterprise image (Server or GitHub AE), you can use Liquid conditionals to version the two images.
|
||||
|
||||
```markdown
|
||||
{% ifversion fpt %}
|
||||
{% else %}
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
### Example: An image is updated in a new Enterprise Server release
|
||||
|
||||
Going further with the example ☝️, let's say that the enterprise version of the `foo/bar.png` image will change in the upcoming release 3.1 and the updated image will be used for all future versions of Enterprise. In this case, you would move the existing `/assets/images/enterprise/foo/bar.png` image to `/assets/images/enterprise/3.0`. You will then add the new 3.1 image back to the original location `/assets/images/enterprise/foo/bar.png`.
|
||||
|
||||
Your Liquid conditional would look like this:
|
||||
|
||||
```markdown
|
||||
{% ifversion fpt %}
|
||||
{% elsif ghes < 3.1 %}
|
||||
{% else %}
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
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.
|
||||
The content in the `contributing` directory has been deprecated. See "[Creating screenshots](https://docs.github.com/en/contributing/writing-for-github-docs/creating-screenshots)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,90 +1 @@
|
||||
# Liquid helpers <!-- omit in toc -->
|
||||
|
||||
We use the [Liquid template language](https://shopify.github.io/liquid/basics/introduction/) (specifically, [this Node.js port](https://github.com/harttle/liquidjs)) and a custom `{% ifversion ... %}` tag to create versions of our documentation.
|
||||
|
||||
Note: If you are an open source contributor, you should not worry about versioning content. This document is only here as reference.
|
||||
|
||||
:arrow_upper_left: TOC
|
||||
|
||||
## Versioned documentation
|
||||
|
||||
We provide versioned documentation for users of GitHub.com plans and Enterprise Cloud, Enterprise Server, and GitHub AE. If multiple versions of a page exist on the site, readers can choose the version from the version picker at the top of the page.
|
||||
|
||||
### GitHub.com
|
||||
|
||||
Documentation for GitHub.com has two possible versions:
|
||||
|
||||
#### Free, Pro, or Team plans
|
||||
|
||||
For Free, Pro, or Team plans on GitHub.com, use `free-pro-team@latest`. The short name is `fpt`.
|
||||
|
||||
#### Enterprise Cloud
|
||||
|
||||
For GitHub Enterprise Cloud, use `enterprise-cloud@latest`. The short name is `ghec`.
|
||||
|
||||
### Enterprise Server
|
||||
|
||||
Documentation for Enterprise Server has multiple versions and can be divided into two types: documentation for **supported releases** (we support four at any one time), and documentation for **deprecated releases** (we do not link to these on the Docs site but we support a "frozen" snapshot of these docs in perpetuity, so they can still be accessed if you know the URLs). See `lib/enterprise-server-releases.js` for a list.
|
||||
|
||||
The versions are named `enterprise-server@<release>`. The short name is `ghes`. In Liquid conditionals, we can specify ranges, like `ghes > 3.0`. (See more on operators below.)
|
||||
|
||||
### GitHub AE
|
||||
|
||||
Versioning for GitHub AE uses the `github-ae@latest` version. The short name is `ghae`.
|
||||
|
||||
## Versioning in the YAML frontmatter
|
||||
|
||||
Use the `versions` property within the file's frontmatter to define which products an entire page applies to. For more information, see [the _content_ directory's README](/content#versions).
|
||||
|
||||
## Liquid conditional operators
|
||||
|
||||
If you define multiple products in the `versions` key within a page's YAML frontmatter, you can use the conditional operators `ifversion`/`else` (or `ifversion`/`elsif`/`else`) in the Markdown to control how the site renders content on the page for a particular product. For example, a feature may have more options on Dotcom than on GitHub Enterprise Server, so you can version the content for both Dotcom and GitHub Enterprise Server via the `versions` frontmatter, and use Liquid conditionals to describe the additional options for Dotcom.
|
||||
|
||||
Important notes:
|
||||
|
||||
* Use `ifversion` for product-based versioning and [feature-based versioning](#feature-based-versioning).
|
||||
* Do not use `if` or `unless`.
|
||||
* Make sure to use `elsif` and not `else if`. Liquid does not recognize `else if` and will not render content inside an `else if` block.
|
||||
|
||||
### Comparison operators
|
||||
|
||||
For versions that don't have numbered releases (like `fpt` and `ghae`), you have two options:
|
||||
|
||||
* `{% ifversion ghae %}`
|
||||
* `{% ifversion not ghae %}`
|
||||
|
||||
For versions that have numbered releases (currently only `ghes`), you can do the same for content that is either available in all of the releases or not available in any of the releases:
|
||||
|
||||
* `{% ifversion ghes %}`
|
||||
* `{% ifversion not ghes %}`
|
||||
|
||||
If you need to denote content that is only available (or not available) in **certain** releases, you can use the following operators:
|
||||
|
||||
|Operator | Meaning| Example
|
||||
|--|--|--|
|
||||
|`=`| Equal to| `{% ifversion ghes = 3.0 %}`
|
||||
|`>`| Newer than| `{% ifversion ghes > 3.0 %}`
|
||||
|`<`| Older than| `{% ifversion ghes < 3.0 %}`
|
||||
|`!=`| Not equal to| `{% ifversion ghes != 3.0 %}` (don't use `not` in ranges)
|
||||
|
||||
The Liquid operators `==`, `>=`, and `<=` are not supported in the GitHub Docs.
|
||||
|
||||
### Logical operators
|
||||
|
||||
When **all** operands must be true for the condition to be true, use the operator `and`:
|
||||
|
||||
```
|
||||
{% ifversion ghes > 2.21 and ghes < 3.1 %}
|
||||
```
|
||||
|
||||
When **at least one** operand must be true for the condition to be true, use the operator `or`:
|
||||
|
||||
```
|
||||
{% ifversion fpt or ghes > 2.21 %}
|
||||
```
|
||||
|
||||
Do **not** use the operators `&&` or `||`. Liquid does not recognize them, and the content will not render in the intended versions.
|
||||
|
||||
### Feature-based versioning
|
||||
|
||||
You can define an arbitrarily named feature and associate specific product versions with that named feature using feature-based versioning. When you use the named version in a Liquid conditional block, the versions that you associate will apply to the content within the block. If the versioning for the feature changes, you can update one file instead of every individual Liquid tag. You can use the `else` operator with feature-based versioning, but not the `not` operator. For more information, see [data/features/README.md](/data/features).
|
||||
The content in the `contributing` directory has been deprecated. See "[Versioning documentation](https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation#versioning-with-liquid-conditional-operators)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# Permalinks
|
||||
|
||||
Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`versions` frontmatter](content#versions).
|
||||
|
||||
For example, an article that is available in currently supported versions will have permalink URLs like the following:
|
||||
|
||||
* `/en/github/getting-started-with-github/set-up-git`
|
||||
* `/en/enterprise-server@2.22/github/getting-started-with-github/set-up-git`
|
||||
* `/en/enterprise-server@2.21/github/getting-started-with-github/set-up-git`
|
||||
* `/en/enterprise-server@2.20/github/getting-started-with-github/set-up-git`
|
||||
* `/en/enterprise-server@2.19/github/getting-started-with-github/set-up-git`
|
||||
|
||||
An article that is not available in Enterprise will have just one permalink:
|
||||
|
||||
* `/en/github/getting-started-with-github/set-up-git`
|
||||
|
||||
**If you are a content contributor:** You don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article you can just use its relative location:
|
||||
|
||||
* `/github/getting-started-with-github/set-up-git`
|
||||
@@ -1,51 +1 @@
|
||||
# Redirects
|
||||
|
||||
There are a number of ways to configure redirects in the site.
|
||||
|
||||
## Local redirects
|
||||
|
||||
Within docs.github.com, you can redirect from one file to another or from one version to another.
|
||||
|
||||
### Redirects across files
|
||||
|
||||
Sometimes we change the name of an article but want its old URL to redirect to its new URL. For these types of redirects, we use `redirect_from` frontmatter. See [/content#redirect_from](/content#redirect_from) for details.
|
||||
|
||||
### Automatic redirects for URLs that do not include a version
|
||||
|
||||
If a URL for a docs page is entered without a version segment (e.g., `https://docs.github.com/foo` instead of `https://docs.github.com/<version>/foo`), the site will automatically redirect it to the **first available version** of the page. The order of precedence is specified in `lib/all-versions.js`, where the current order is:
|
||||
|
||||
1. Free, Pro, & Team (`fpt`)
|
||||
1. Enterprise Cloud (`ghec`)
|
||||
1. Enterprise Server (`ghes`)
|
||||
1. GitHub AE (`ghae`)
|
||||
|
||||
So if a page `foo.md` is only available in Cloud and Server, the link `https://docs.github.com/foo` will automatically redirect to `https://docs.github.com/enterprise-cloud@latest/foo` because Cloud has precedence over Server.
|
||||
|
||||
If `foo.md` is available in Free, Pro, & Team, no redirect will occur because `fpt` pages do not have a version segment, so the `fpt` content at `https://docs.github.com/foo` will render.
|
||||
|
||||
### Redirects across versions
|
||||
|
||||
If you want the URL for one version of an article to redirect to a URL for another version, you must use [/src/redirects/lib/static/redirect-exceptions.txt](/src/redirects/lib/static/redirect-exceptions.txt) instead. For example, if you remove the Free, Pro, & Team (`fpt`) version of an article, the URL will [automatically redirect](#automatic-redirects-for-urls-that-do-not-include-a-version) to the next available version of the page. If you want it to redirect to a version that is **lower in the order of precedence**, or to a different page entirely, you must specify an exception.
|
||||
|
||||
Another example: we removed the `ghes` version of "[Exporting member information for your organization](https://docs.github.com/en/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization)," but we don't want URLs that include the `enterprise-server@<release>` version segment to 404. In order to redirect `ghes` URLs to another version (such as `ghec`), we need to add an exception.
|
||||
|
||||
Each entry in [the exceptions file](/src/redirects/lib/static/redirect-exceptions.txt) should start with the path you want to redirect _to_, including the version, followed by an unordered list of the paths you want to redirect _from_:
|
||||
|
||||
```
|
||||
/enterprise-cloud@latest/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
|
||||
- /enterprise-server@3.3/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
|
||||
- /enterprise-server@3.4/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
|
||||
- /enterprise-server@3.5/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
|
||||
```
|
||||
|
||||
## External redirects
|
||||
|
||||
Sometimes the canonical home of some content moves outside the help site. For these types of redirects, we add entries to [/src/redirects/lib/external-sites.json](/src/redirects/lib/external-sites.json).
|
||||
|
||||
## Custom redirects
|
||||
|
||||
We also have custom routing code that automatically creates redirects under the hood for things like moved Admin guide pages. This code lives in [/src/redirects/lib/get-old-paths-from-permalink.js](/src/redirects/lib/get-old-paths-from-permalink.js). All redirects for the site are compiled when the server starts by [/src/redirects/lib/precompile.js](/src/redirects/lib/precompile.js).
|
||||
|
||||
See [Links and image paths](../content/README.md#links-and-image-paths) for info on how links and images are rewritten on the fly at page render time.
|
||||
|
||||
See [Troubleshooting](./troubleshooting.md#debugging-locally) for info on viewing the redirects for any page.
|
||||
The content in the `contributing` directory has been deprecated. See "[Configuring redirects](https://docs.github.com/en/contributing/writing-for-github-docs/configuring-redirects)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,13 +1 @@
|
||||
### Self review
|
||||
|
||||
You should always review your own PR first.
|
||||
|
||||
For content changes, make sure that you:
|
||||
|
||||
- [ ] Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).
|
||||
- [ ] Compare your pull request's source changes to staging to confirm that the output matches the source and that everything is rendering as expected. This helps spot issues like typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Remember that lists and tables can be tricky.
|
||||
- [ ] Review the content for technical accuracy.
|
||||
- [ ] Review the entire pull request using the [translations guide for writers](./translations-for-writers.md).
|
||||
- [ ] Copy-edit the changes for grammar, spelling, and adherence to the [style guide](https://github.com/github/docs/blob/main/contributing/content-style-guide.md).
|
||||
- [ ] Check new or updated Liquid statements to confirm that versioning is correct.
|
||||
- [ ] If there are any failing checks in your PR, troubleshoot them until they're all passing.
|
||||
The content in the `contributing` directory has been deprecated. See "[Self review checklist](https://docs.github.com/en/contributing/collaborating-on-github-docs/self-review-checklist)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,31 +1 @@
|
||||
# Tool switcher
|
||||
|
||||
In some articles, we write content tailored to different tools (GitHub UI, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, GitHub Enterprise Importer CLI, GraphQL API, etc.) Tools may have different conceptual or procedural information. People can select a tool to see only the content that is relevant to the tool. People can use the tool switcher in two ways when reading the docs.
|
||||
|
||||
**Exploring**
|
||||
For tasks that can be completed with different tools, the tool switcher signals to people that there are multiple ways a task can be done (like using the CLI or Desktop, instead of the UI).
|
||||
|
||||
**Getting to the point**
|
||||
When someone knows how they want to do a task and doesn’t need to see additional options, the tool switcher removes less relevant content, so they can find exactly what they need.
|
||||
|
||||
We use tool tags to demarcate information for each tool. On rare occasions, we will add new tools.
|
||||
|
||||
## Tool tags
|
||||
Tool tags are a key value pair. The key is the tag you use to refer to the tool in the article and the value is how the tool will be identified on the tool picker at the top of the article. The existing tools are in [`lib/all-tools.js`](../lib/all-tools.js).
|
||||
|
||||
### When to use tool tags
|
||||
We only use tool tags if an article must have tool-specific information to help people accomplish their tasks. Just because multiple tools exist for a procedure does not mean we should document each tool individually. If the conceptual information behind a task or the procedural steps for accomplishing a task are different, and we want people to be able to accomplish the task with multiple tools, we use tool tags to present the relevant information in an article.
|
||||
|
||||
Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts described in an article change based on what tool someone uses.
|
||||
|
||||
### How to use tool tags
|
||||
Tool tags are Liquid tags that wrap content specific to a tool. For more information on using tool tags in an article, see the [content markup reference](./content-markup-reference.md#tool-tags).
|
||||
|
||||
Put tools in alphabetical order. By default, the first tool tag will be selected for an article. You can define a different default tool for an article in the article's frontmatter. For more information, see the [content README](../content/README.md#defaulttool). You can also link to an article with a specific tool selected by adding `?tool=TOOLNAME` to the end of the link. For more information, see the [content style guide](./content-style-guide.md#links-to-a-specific-tool).
|
||||
|
||||
Only include a maximum of eight different tools in an article. Including more tools causes the tool switcher tabs to overflow with an article's table of contents, which prevents people from using either the tool switcher or table of contents. It is unlikely that you will ever need to include eight separate tools in an article. In general, plan to use as few separate tools as possible in an article.
|
||||
|
||||
## Adding new tools
|
||||
If a writer determines that adding a new tool is the only way to accurately document something, they should explain their reasoning in the content planning stage. Whoever reviews content plan should consider if there are any alternative ways to address the documentation need without adding a new tool. If a new tool is the only way to create accurate documentation, the new tool should be added. If there is an alternative content solution that does not add a new tool, that option should be used.
|
||||
|
||||
To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](../lib/all-tools.js) as a key-value pair. Add new tools in alphabetical order.
|
||||
The content in the `contributing` directory has been deprecated. See "[Creating tool switchers in articles](https://docs.github.com/en/contributing/writing-for-github-docs/creating-tool-switchers-in-articles)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,35 +1 @@
|
||||
# Translations guide for writers
|
||||
|
||||
Use the following checklist to help make your files more translation-friendly. For additional information, refer to the [style guide](../content-style-guide.md).
|
||||
|
||||
- [ ] Use examples that are generic and can be understood by most people.
|
||||
- [ ] Avoid examples that are controversial or culturally specific to a group.
|
||||
- [ ] Write in active voice.
|
||||
- [ ] Write simple, short, and easy-to-understand sentences.
|
||||
- [ ] Avoid using too many pronouns that can make text unclear.
|
||||
- [ ] Avoid using slang and jokes.
|
||||
- [ ] Avoid negative sentences.
|
||||
- [ ] Use industry-standard acronyms whenever possible and explain custom acronyms.
|
||||
- [ ] Use indicative mood.
|
||||
- [ ] Eliminate redundant and wordy expressions.
|
||||
- [ ] Avoid the excessive use of stacked modifiers (noun strings). The translator can misunderstand which noun is the one being modified.
|
||||
- [ ] Avoid invisible plurals in which it is not clear if the first noun is meant to be singular or plural.
|
||||
- [ ] Avoid nominalization.
|
||||
- [ ] Avoid using ambiguous modal auxiliary verbs.
|
||||
- [ ] Avoid gender-specific words.
|
||||
- [ ] Avoid prepositional phrases.
|
||||
- [ ] Avoid vague nouns and pronouns (vague sentence subject).
|
||||
- [ ] Keep inline links to a minimum. If they are necessary, preface them with a phrase such as "For more information, see "Link title". Alternatively, add relevant links to a "Further reading" section at the end of the topic.
|
||||
|
||||
## Examples
|
||||
|
||||
| Guideline | Avoid | Use instead |
|
||||
| --------- | ----- | ----------- |
|
||||
| Avoid country specific information. | 800 numbers, addresses, etc. | If necessary, mention what countries the information applies to. |
|
||||
| Avoid the excessive use of stacked modifiers (noun strings). This can lead to incorrect translations because it is not easy to tell what modifies what. | “public repository default source settings” or “OAuth app access restrictions” | "Default source settings for the public repository" or "restrictions for OAuth app access." If using a stacked modifier is essential, make sure the background information and context are clear so the linguist can understand which noun is being modified. |
|
||||
| Avoid invisible plurals. | "Program update" or "File retrieval". Is this an update of one program or a general procedure for multiple programs? For "File retrieval", are you retrieving one file or all of them? | Write the sentence more clearly or provide additional context to eliminate ambiguity that can result in an incorrect translation. |
|
||||
| Avoid nominalization. | "To reach a conclusion" | Use "Conclude." |
|
||||
| Avoid using ambiguous modal auxiliary verbs. | May, might, ought, could, used to, etc. | Be more clear when writing to avoid ambiguity. |
|
||||
| Avoid prepositional phrases. | "According to the repository log..." or "After trying many times..." | Write the sentence more directly. |
|
||||
| Avoid vague nouns and pronouns. | "Maintainers and contributors have access to files and comments. In the pull request they make changes to it." In this example, it is not clear if the changes are being made to the file or to the comments. Another example: “After saving the file in the folder, the user deleted it.” In this sentence, it is not clear what was deleted (a file or a folder). | If a pronoun seems to refer to more than one antecedent, either reword the sentence to make the antecedent clear or replace the pronoun with a noun to eliminate ambiguity. |
|
||||
| Keep inline links to a minimum. | Read [more about OAuth2.](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](https://docs.github.com/en/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites. | OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth apps](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](https://docs.github.com/en/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization)." |
|
||||
The content in the `contributing` directory has been deprecated. See "[Writing content to be translated](https://docs.github.com/en/contributing/writing-for-github-docs/writing-content-to-be-translated)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,131 +1 @@
|
||||
# Troubleshooting <!-- omit in toc -->
|
||||
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Troubleshooting server tests that fail locally but pass in CI](#troubleshooting-server-tests-that-fail-locally-but-pass-in-ci)
|
||||
- [Staging deployment stalled](#staging-deployment-stalled)
|
||||
- [CI stalled or stuck](#ci-stalled-or-stuck)
|
||||
- [Can't run the site locally](#cant-run-the-site-locally)
|
||||
- [Failed staging deployment](#failed-staging-deployment)
|
||||
- [500 error on specific page on staging](#500-error-on-specific-page-on-staging)
|
||||
- [Check internal links](#check-internal-links)
|
||||
- [Check external links](#check-external-links)
|
||||
- [Debugging locally](#debugging-locally)
|
||||
- [Liquid processing](#liquid-processing)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Troubleshooting server tests that fail locally but pass in CI
|
||||
|
||||
If you run the tests locally and get failures in `tests/rendering/server.js` around static assets, stylesheets, and/or the client-side JavaScript bundle, but **the same tests pass in CI** on a PR, you likely need to run `npm run build`. This is a one-time command that creates static assets locally.
|
||||
|
||||
See [`development.md`](./development.md) for more info.
|
||||
|
||||
### Staging deployment stalled
|
||||
If a staging deployment is pending for more than 5-10min, try the following:
|
||||
|
||||
1. Close the PR (don't delete the branch) and reopen it. This will trigger a new staging deployment. It won't break anything.
|
||||
2. If that doesn't work, trigger a new staging deployment by pushing an empty commit on the command line:
|
||||
|
||||
```
|
||||
git commit --allow-empty -m 'empty commit to redeploy staging'
|
||||
```
|
||||
|
||||
### CI stalled or stuck
|
||||
:yellow_heart: If tests are stuck yellow for more than an hour, rerun CI by pushing an empty commit on the command line:
|
||||
|
||||
```
|
||||
git commit --allow-empty -m 'empty commit to rerun CI'
|
||||
```
|
||||
|
||||
### Can't run the site locally
|
||||
If you are running `npm start` and get a `Cannot find module` error, try:
|
||||
|
||||
```
|
||||
npm install
|
||||
```
|
||||
|
||||
If that doesn't fix it, try:
|
||||
|
||||
```
|
||||
rm -rf node_modules
|
||||
npm install
|
||||
```
|
||||
|
||||
### Failed staging deployment
|
||||
Check out the branch and run the site locally:
|
||||
|
||||
```
|
||||
npm start
|
||||
```
|
||||
|
||||
Go to https://localhost:4000
|
||||
|
||||
You should see more information about the error in your browser or in your Terminal (or both).
|
||||
|
||||
If you see an error like this:
|
||||
|
||||
```
|
||||
error parsing file: /Users/z/git/github/docs/content/dotcom/articles/troubleshooting-custom-domains-and-github-pages.md
|
||||
(node:89324) UnhandledPromiseRejectionWarning: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 14:
|
||||
redirect_from:
|
||||
^
|
||||
```
|
||||
|
||||
make sure single quotes are properly escaped in the frontmatter. Also, check the formatting in `redirect_from` blocks.
|
||||
|
||||
### 500 error on specific page on staging
|
||||
Check out the branch and run the site locally:
|
||||
|
||||
```
|
||||
npm start
|
||||
```
|
||||
|
||||
Go to whatever page is 500ing on staging on your local server: https://localhost:4000/page-with-error
|
||||
|
||||
Again, you should see more information about the error either in your browser or in your Terminal (or both). Staging just shows Oops, but the local server should a stack trace for debugging.
|
||||
|
||||
## Check internal links
|
||||
|
||||
The `check internal links` test reports any broken links on the site, including images. The test reports the URL of the broken link, _not_ the file that includes that link, so you'll need to search the `docs` repository to find the file.
|
||||
|
||||
Broken images include `assets/images/` in the URL and are often caused by images being versioned for previous versions of GHES but not uploaded to the appropriate folder in S3. Search the `docs` repository for the file name (e.g., `assets/images/help/repository/security-tab.png`), then make sure the image is versioned correctly in each result. If the image is in a reusable, you'll also need to search for each occurrence of that reusable. If the image is versioned correctly, upload the image to the appropriate folder(s) in S3.
|
||||
|
||||
For broken links to articles on our site, find the file that contains the link by searching the `docs` repository for the file name (e.g., `incorporating-feedback-in-your-pull-request`). Try the following fixes:
|
||||
|
||||
1. Make sure the link is versioned correctly. For example, if the article only exists for 2.17+, make sure the link is versioned for 2.17+.
|
||||
2. If an article that is available for GHES links to a dotcom-only article, include the version in the path to prevent the URL from automatically converting to include a GHES version number:
|
||||
```
|
||||
[{{ site.data.variables.product.prodname_github_connect }} Addendum to the {{ site.data.variables.product.prodname_enterprise }} License Agreement](/free-pro-team@latest/articles/github-connect-addendum-to-the-github-enterprise-license-agreement/)"
|
||||
```
|
||||
|
||||
## Check external links
|
||||
|
||||
For broken external links, investigate whether the site is permanently removed. If so, find an alternative site that provides equivalent context.
|
||||
|
||||
## Debugging locally
|
||||
|
||||
During development, you can visit any page on `http://localhost:4000` and add `?json=page` to the end of the path to show some underlying information that may be helpful for debugging. In addition to basic info like title and intro, these are a few fields that may be useful.
|
||||
|
||||
| Field | Description |
|
||||
| ----- | ----------- |
|
||||
|`productVersions` | Shows what the site is parsing from the [`productVersions` frontmatter](content#productVersions).
|
||||
| `permalinks` | Shows all [permalinks](contributing/permalinks.md) that the site is generating for the page.
|
||||
| `redirect_from` | Shows the hardcoded redirects in the [`redirect_from` frontmatter](content#redirect_from).
|
||||
| `redirects` | Shows all redirects that the site is generating for the page.
|
||||
| `includesPlatformSpecificContent` | Shows whether the site detects any [platform-specific content](#operating-system-tags) on the page.
|
||||
|
||||
## Liquid processing
|
||||
|
||||
If your text or code example includes `{` or `}` that should render, you need to wrap it in `{% raw %}` `{% endraw %}` to disable Liquid processing for that section. For example:
|
||||
|
||||
- **Use**:
|
||||
|
||||
```
|
||||
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
|
||||
```
|
||||
|
||||
- **Avoid**:
|
||||
|
||||
```
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
The content in the `contributing` directory has been deprecated. See "[Troubleshooting your environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,186 +1 @@
|
||||
# Using videos in GitHub Docs content
|
||||
|
||||
Videos are rarely used in the GitHub Docs. When videos are necessary to provide the best user experience for an article, they are used in conjunction with written text. Videos are not a replacement for written content.
|
||||
|
||||
Use these guidelines to determine if a video is appropriate to include in an article or on a landing page in the GitHub docs. If you have questions about whether or not a video would be a good addition to the docs, contact the Docs Content Strategy team.
|
||||
|
||||
If you add a link to a video or embed a video in the GitHub Docs, add the video's metadata to the "[Videos in GitHub Docs](#videos-in-github-docs)" section below.
|
||||
|
||||
The Docs team does not create or maintain video content. Videos are purely supplemental to help communicate significant or complex topics, and should be used sparingly because they are not a content type owned by the Docs team.
|
||||
|
||||
## Video checklist
|
||||
|
||||
Use this checklist to quickly determine if a video might be appropriate to add to an article or landing page.
|
||||
|
||||
- [ ] Is the video the only way to communicate the information?
|
||||
- [ ] Does GitHub own the video?
|
||||
- [ ] Is the video well produced? (See the [Best practices](#best-practices) below for more information)
|
||||
- [ ] Is the video accessible? (See the [Accessibility requirements](#accessibility-requirements))
|
||||
- [ ] Is the video less than five minutes long?
|
||||
- [ ] Does the video have a specific audience and purpose in the docs? If it is only relevant to a particular product or feature, you must use [versioning](#versioning)
|
||||
|
||||
If you answer "no" to any of these items, the video is not suitable for adding to the GitHub docs.
|
||||
|
||||
### Maintenance
|
||||
|
||||
Does the video have a maintenance schedule or a team directly responsible for auditing and updating the content if it becomes out of date?
|
||||
|
||||
If yes, you can include the video without any additional steps.
|
||||
|
||||
If no, create an issue with an appropriate target date to review or remove the video.
|
||||
|
||||
## Best practices
|
||||
|
||||
Use these best practices to help determine if a video is well produced and is of a high enough quality to be included in the GitHub Docs.
|
||||
|
||||
Good videos introduce an instructional agenda that includes steps and goals so that someone watching quickly knows what they will learn. Videos are demonstrative, both showing and explaining the relevant steps that are performed. Videos should be engaging and encouraging. Videos must be well produced to be included in the GitHub docs. A well produced video meets accessibility requirements, has professional narration (if it is a narrated video), has clear visuals, and comes from a reputable source such as GitHub or Microsoft.
|
||||
|
||||
Videos are broadly grouped into three categories: product overviews, feature videos, and tutorials. These descriptions are generalizations of each video type. Some videos might not fit perfectly in one category, but can still be useful without meeting the exact guidelines.
|
||||
|
||||
### Product overviews
|
||||
- **Purpose**: Briefly explain what the product is, showcase the main functionality, and get people interested
|
||||
- **Length**: Less than a minute
|
||||
- **Possible audiences**: People who want to know if a feature is useful for their goals, people who are new to GitHub and trying to understand what the products do
|
||||
- **Possible locations in the docs**: Landing pages and guides
|
||||
|
||||
### Feature videos
|
||||
- **Purpose**: Supplement conceptual or procedural content
|
||||
- **Length**: As short as possible, without exceeding five minutes. Break longer content into multiple shorter, focused videos
|
||||
- **Possible audiences**: People who are learning about or how to use a feature
|
||||
- **Possible locations in the docs**: Guides, conceptual articles, procedural articles
|
||||
|
||||
### Tutorials
|
||||
- **Purpose**: Help novice users get going with a product, drive adoption, or explain complex functionalities
|
||||
- **Length**: Individual videos should be five minutes or less. Complex topics can have a series of shorter videos spread across an article. Total length should be a maximum of 15 minutes
|
||||
- **Possible audiences**: New users of features or products
|
||||
- **Possible locations**: Guides
|
||||
|
||||
## When to use videos
|
||||
|
||||
We might use videos instead of other visuals such as screenshots or diagrams when it is important to show movement or changes in state, like when someone navigates from one screen to another or demos a feature that involves progressing through multiple menus. However, screenshots or text may be sufficient to explain these procedures.
|
||||
|
||||
Videos can also be helpful to introduce features or products where a 30 second video can supplement information that requires multiple paragraphs to write.
|
||||
|
||||
Use videos that explain the value of the procedure or concept that they are showing.
|
||||
|
||||
## When to not use videos
|
||||
|
||||
Do not use videos for features that change quickly and may make videos out of date. Do not use videos that contradict the written content or violate any parts of the [content style guide](./content-style-guide.md). Do not use videos that just show a task without explaining or elaborating on the procedure. Do not use a video just because a video exists. Videos must be useful and relevant to our users, which includes staying accurate over time.
|
||||
|
||||
## Accessibility requirements
|
||||
|
||||
These are the minimum accessibility requirements for a video to be included in the GitHub docs. If a video violates any of these requirements, it cannot be added to the docs. Videos must meet the MAS-C standards for accessibility.
|
||||
|
||||
- No flashing or strobe effects
|
||||
- Must have [closed captions](https://webaim.org/techniques/captions/#captions). See "[Creating video captions](#creating-video-captions)" below for more information
|
||||
- No graphics overlap with where captions appear
|
||||
- Typography must be legible
|
||||
- Any overlays must meet [WCAG contrast standards](https://webaim.org/articles/contrast/)
|
||||
- Any text must be on the screen long enough to be read (the text should appear onscreen for longer than it takes to read it out loud twice)
|
||||
- Must have proofread [descriptive transcripts](https://www.w3.org/WAI/media/av/transcripts/) for what happens scene-by-scene. See "[Creating video transcripts](#creating-video-transcripts)" below for more information
|
||||
- Videos do not autoplay
|
||||
|
||||
### Creating video captions
|
||||
|
||||
Videos must have human-generated captions before being added to the Docs site. You can use auto caption technology to help create the captions, but they must be proofread and edited for accuracy by a person. If the video hosting service has a native caption tool, like YouTube, you can use that tool to prepare captions or create a properly formatted `SRT` or `VTT` transcript file to upload with the video.
|
||||
|
||||
Creating captions is part of the process of producing accessible videos, so the owner of a video being added to GitHub Docs should provide captions.
|
||||
|
||||
#### Guidelines for captions
|
||||
|
||||
Where possible, captions should exactly match the words spoken in the video. Do not paraphrase or truncate captions, unless serious time constraints mean it would be difficult for someone to read the captions in the time given.
|
||||
|
||||
Captions must be synchronized to appear at approximately the same time as the audio. Captions should always be timed to appear on screen at the moment the speaker begins talking. For fast speech, where it would be difficult to read captions timed precisely to the audio, you can extend the captions to stay on screen after the speech has finished.
|
||||
|
||||
If a video has multiple speakers, identify the speakers in the captions. Do this by adding the speaker's name, or a descriptive name such as `Developer`, before the start of the sentence. For example: `Jimmy: Hello.`. You only need to do this when the speaker changes, not for every line of dialogue. If it's obvious from the visuals who is speaking, you do not need to identify the speaker.
|
||||
|
||||
Captions must be one or two lines, and no more than 32 characters per line. Put each new sentence on a new line. If you need to break a line mid-sentence, do so at a logical point, for example after commas or before conjunctions like `and` or `but`.
|
||||
|
||||
#### Adding and editing captions on YouTube
|
||||
|
||||
For videos hosted on YouTube, see "[Add subtitles and captions](https://support.google.com/youtube/answer/2734796?hl=en&ref_topic=7296214)" and "[Edit or remove captions](https://support.google.com/youtube/answer/2734705?hl=en&ref_topic=7296214)" in the YouTube docs.
|
||||
|
||||
### Creating video transcripts
|
||||
|
||||
For every video linked or embedded in the docs, we must have a descriptive transcript of the video. Transcript articles are formatted like other articles, with YAML frontmatter and Markdown content. To add a transcript to the Docs site, create an article in [`content/video-transcripts`](https://github.com/github/docs/tree/main/content/video-transcripts), and include the transcript as the article's body text. Give the article a filename like `transcript-VIDEO-NAME.md` and a `title` frontmatter property of `Transcript - VIDEO NAME`. Add the article to the `index.md` file in the `video-transcripts` directory.
|
||||
|
||||
Do not use Liquid variables or reusables to replace things like product names in the transcript. The transcript should be faithful to the audio in the video, and we should not change any text in the transcript as a result of updating a variable or reusable after the video was produced.
|
||||
|
||||
Creating transcripts is part of the process of producing accessible videos, so the owner of a video being added to the docs site should provide the content for a transcript.
|
||||
|
||||
You can use captions as the foundation for a transcript. Edit the captions to remove any timestamps and include the relevant information detailed below. A descriptive transcript includes a text version of both audio and visual information needed to understand the content of a video.
|
||||
|
||||
- If a video has multiple speakers, identify the speakers in the transcript
|
||||
- Format the transcript in logical paragraphs, lists, and sections. If it helps people understand the content, you may add headers to sections. Consider how someone would get information from the transcript if they are not also viewing the video
|
||||
- Add any onscreen text, relevant visual elements, or non-speech sounds that are not included in the captions. Place these descriptions after the spoken text that accompanies them in the video. Format visual information in brackets. For example, `[Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]`
|
||||
- Add a `product_video` property to the transcript article's YAML frontmatter. The value of the `product_video` property is the YouTube URL of the video. The video's YouTube URL will display as an external link in the transcript article
|
||||
- At the end of the transcript, link to the landing page for the product the video is about using the pattern `For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page).`
|
||||
|
||||
See "[Text Transcript with Description of Visuals](https://www.w3.org/WAI/perspective-videos/captions/#transcript)" in the W3C docs for more examples of audio and visual transcriptions.
|
||||
|
||||
#### Linking to transcripts from externally hosted videos
|
||||
|
||||
Add a link to the article with a video's transcript in the description of the video on the platform where it is hosted. For more information, see "[Edit video settings](https://support.google.com/youtube/answer/57404?)" in the YouTube documentation.
|
||||
|
||||
#### Linking to transcripts for embedded videos
|
||||
|
||||
In any content with an embedded video, add a `product_video_transcript` property below the `product_video` property in the YAML frontmatter. The value of `product_video_transcript` is a link to the transcript article in the `video-transcripts` directory.
|
||||
|
||||
```yaml
|
||||
title: Example product landing page
|
||||
product_video: 'https://www.youtube-nocookie.com/embed/URL'
|
||||
product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE
|
||||
```
|
||||
|
||||
## Titles for videos
|
||||
|
||||
Titles should be descriptive and follow the guidelines for titles in the [content model](./content-model.md#titles).
|
||||
|
||||
## Versioning
|
||||
|
||||
If a video is only relevant for specific GitHub products (Free, Pro and Team; GitHub Enterprise Server; GitHub AE; and GitHub Enterprise Cloud), the video must be versioned for those products. Use [Liquid](liquid-helpers.md) conditional statements to version the videos appropriately. 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.
|
||||
|
||||
## Video hosting
|
||||
|
||||
Videos must be hosted somewhere that GitHub owns and can grant the Docs team access to. Videos should not track users or use cookies. Currently, GitHub's videos are hosted on YouTube and added to the docs using the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) by changing the domain for the embedded URL from `https://www.youtube.com/VIDEO` to `https://www.youtube-nocookie.com/VIDEO`.
|
||||
|
||||
## Resources
|
||||
- https://webaim.org
|
||||
- https://www.w3.org/TR/WCAG22/#time-based-media
|
||||
|
||||
## Videos in GitHub Docs
|
||||
|
||||
Add the following metadata for each video added to the GitHub Docs.
|
||||
|
||||
```markdown copy
|
||||
Title: Video title
|
||||
URL: YouTube.com/
|
||||
Description: One sentence
|
||||
Product: e.x. Projects
|
||||
Versions: e.x. fpt, GHES > 3.2
|
||||
Date added: YYYY-MM-DD
|
||||
Location: /where/in/docs
|
||||
Transcript: ./content/video-transcripts/filename
|
||||
```
|
||||
|
||||
```
|
||||
Title: Codespaces - Your instant dev box in the cloud
|
||||
URL: https://www.youtube-nocookie.com/embed/_W9B7qc9lVc
|
||||
Description: A 1.5 minute overview of GitHub Codespaces.
|
||||
Product: Codespaces
|
||||
Versions: fpt, ghec
|
||||
Date added: 2021-05-11
|
||||
Location: /content/codespaces/index.md
|
||||
Transcript: /video-transcripts/transcript-codespaces-your-instant-dev-box-in-the-cloud
|
||||
```
|
||||
|
||||
```
|
||||
Title: Using Projects for feature planning
|
||||
URL: https://www.youtube-nocookie.com/embed/yFQ-p6wMS_Y
|
||||
Description: Check out all the cool new things you can do with your GitHub Projects powered by GitHub Issues
|
||||
Product: Issues
|
||||
Versions: projects-v2
|
||||
Date added: 2023-05-09
|
||||
Location: /content/issues/index.md
|
||||
Transcript: /video-transcripts/transcript-using-projects-for-feature-planning
|
||||
```
|
||||
The content in the `contributing` directory has been deprecated. See "[Using videos in GitHub Docs](https://docs.github.com/en/contributing/writing-for-github-docs/using-videos-in-github-docs)" in the GitHub Docs for the maintained version of this article.
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# Working in the github/docs repository
|
||||
|
||||
Here's some information that might be helpful while working on a Docs PR:
|
||||
|
||||
- [Development](/contributing/development.md) - This short guide describes how to get this app running on your local machine.
|
||||
|
||||
- [Content markup reference](/contributing/content-markup-reference.md) - All of our content is written in GitHub-flavored Markdown, with some additional enhancements.
|
||||
|
||||
- [Content style guide for GitHub Docs](/contributing/content-style-guide.md) - This guide covers GitHub-specific information about how we style our content and images. It also links to the resources we use for general style guidelines.
|
||||
|
||||
- [Content model](/contributing/content-model.md) and [content templates](/contributing/content-templates.md) - The content model describes the purpose of each type of content we use in GitHub Docs and how to write for each type. The templates allow you to quickly get started with new articles.
|
||||
|
||||
- [Reusables](/data/reusables/README.md) - We use reusables to help us keep content up to date. Instead of writing the same long string of information in several articles, we create a reusable, then call it from the individual articles.
|
||||
|
||||
- [Variables](/data/variables/README.md) - We use variables the same way we use reusables. Variables are for short strings of reusable text.
|
||||
|
||||
- [Liquid](/contributing/liquid-helpers.md) - We use liquid helpers to create different versions of our content.
|
||||
|
||||
- [Tests](/tests/README.md) - We use tests to ensure content will render correctly on the site. Tests run automatically in your PR, and sometimes it's also helpful to run them locally.
|
||||
Reference in New Issue
Block a user