jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Splitting up the content model (#42868)

Browse Source 
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
This commit is contained in:
Steve Guntrip
2023-09-29 11:34:06 +01:00
committed by GitHub
parent bc0f928822
commit 83e5beaa09
30 changed files with 725 additions and 665 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md
View File

@@ -53,7 +53,7 @@ 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).
- Review the content for technical accuracy.
- Check your changes for grammar, spelling, and adherence to the [AUTOTITLE](/contributing/writing-for-github-docs/style-guide).
- Check your changes for grammar, spelling, and adherence to the [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide).
- Make sure the text in your pull request will be easy to translate. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated)."
- Check new or updated Liquid statements to confirm that versioning is correct. For more information, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation)."
- Check the preview of any pages you have changed. A preview is automatically generated after you submit a pull request and links are added to the pull request. The preview sometimes takes several minutes before it is ready to view. Confirm that everything is rendering as expected. Checking the preview will help you identify problems such as typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Make sure to check the rendered output for lists and tables, which can sometimes have problems that are difficult to identify in the Markdown.

2
content/contributing/collaborating-on-github-docs/self-review-checklist.md
View File

@@ -12,6 +12,6 @@ Before you submit your changes to the {% data variables.product.prodname_docs %}
- After opening your pull request, view your changes on staging to confirm the article renders as expected and matches the source. This helps spot issues like typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems.
- Review your changes for technical accuracy.
- Review your entire pull request to ensure it follows our guidance on creating content that can be translated. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated)."
- Check your changes for grammar, spelling, and adherence to the style guide. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide)."
- Check your changes for grammar, spelling, and adherence to the style guide. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)."
- If you have added new versioning or made changes to existing versioning, confirm your changes render as expected while viewing each available version of the article.
- If there are any failing checks in your pull request, troubleshoot them until they're all passing.

6
content/contributing/index.md
View File

@@ -9,14 +9,14 @@ versions:
featuredLinks:
startHere:
- /contributing/writing-for-github-docs/about-githubs-documentation-philosophy
- /contributing/writing-for-github-docs/style-guide
- /contributing/writing-for-github-docs/content-model
- /contributing/style-guide-and-content-model/style-guide
- /contributing/style-guide-and-content-model/about-the-content-model
- /contributing/collaborating-on-github-docs/about-contributing-to-github-docs
changelog:
label: docs
children:
- /writing-for-github-docs
- /syntax-and-versioning-for-github-docs
- /style-guide-and-content-model
- /collaborating-on-github-docs
- /setting-up-your-environment-to-work-on-github-docs
---

32
content/contributing/style-guide-and-content-model/about-combining-multiple-content-types.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: About combining multiple content types
shortTitle: Combining multiple types
intro: 'You can combine multiple content types in a single article to help people complete complex tasks.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
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 is 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
- [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility)
- [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
- [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-github-account/upgrading-your-github-subscription)
- [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode)

117
content/contributing/style-guide-and-content-model/about-the-content-model.md Normal file
View File

@@ -0,0 +1,117 @@
---
title: About the content model
shortTitle: About the content model
intro: 'The content model describes the structure and types of content that we publish.'
product: '{% data reusables.contributing.product-note %}'
redirect_from:
- /contributing/writing-for-github-docs/content-model
versions:
feature: 'contributing'
---
Our content model explains the purpose of each type of content we create within {% data variables.product.prodname_docs %}, and what to include when you write or update an article. We use a content model to ensure that our content consistently, clearly, and comprehensively communicates the information that people need to achieve their goals with {% data variables.product.prodname_dotcom %}.
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 {% data variables.product.prodname_docs %} over time. It is also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you are an open source contributor making your first commit or a writer on the {% data variables.product.prodname_dotcom %} staff 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 {% data variables.product.prodname_docs %} homepage, [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 {% data variables.product.prodname_dotcom %} concepts and practices. For example, the "CI/CD and DevOps" group includes top-level doc sets for {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, and {% data variables.product.prodname_pages %}.
### Adding a doc set to the homepage
The goal of the homepage is to help people find information about the {% data variables.product.prodname_dotcom %} feature or product that they want to learn about. Every item added to 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 {% data variables.product.prodname_dotcom %} 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](/code-security)" top-level doc set, the "[Supply chain security](/code-security/supply-chain-security)," "[Security advisories](/code-security/security-advisories)," "[{% data variables.product.prodname_dependabot %}](/code-security/dependabot)," "[{% data variables.product.prodname_code_scanning_caps %}](/code-security/code-scanning)," and "[{% data variables.product.prodname_secret_scanning_caps %}](/code-security/secret-scanning)" categories are included because each of those categories are the entry point to {% data variables.product.prodname_dotcom %} products and features. "[Security overview](/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 {% data variables.product.prodname_dotcom %} product, feature, or core workflow. All top-level doc sets appear on the {% data variables.product.prodname_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 {% data variables.product.prodname_dotcom %} 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](/free-pro-team@latest/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 {% data variables.product.prodname_dotcom %} someone is using.
- Examples
- [AUTOTITLE](/organizations)
- [AUTOTITLE](/issues)
## Category
Categories are organized around a feature or a discrete set of tasks within a top-level doc set aligned with product themes. A category's subject is narrow enough that its contents are manageable and does not grow too large to use. Some categories appear on the 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.
### 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
- [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github)
- [AUTOTITLE](/pull-requests/committing-changes-to-your-project)
### Intros for categories
All categories have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. 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.
### 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
- [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain)
- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise)
### Intros for map topics
All map topics have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. 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 {% data variables.product.prodname_docs %}––while we use multiple content types, they are 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 information, 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
## 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.

46
content/contributing/style-guide-and-content-model/about-topics.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: About topics
shortTitle: About topics
intro: 'Use topics to make articles searchable.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
Topics are used to filter articles and are searchable across the {% data variables.product.prodname_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 {% data variables.product.prodname_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 {% data variables.product.prodname_actions %}”
- Avoid: `Actions` in an article like "Introduction to {% data variables.product.prodname_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 {% data variables.product.prodname_dotcom %} 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? 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`

38
content/contributing/style-guide-and-content-model/conceptual-content-type.md Normal file
View File

@@ -0,0 +1,38 @@
---
title: Conceptual content type
intro: 'People most often use conceptual content when they are learning about something new to them.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
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.
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
For the conceptual content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#conceptual-article-template)."
- 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 {% data variables.product.prodname_code_scanning %}"
- Avoid: "About scanning your code for vulnerabilities"
## Examples of conceptual content
- Conceptual articles
- [About GitHub Sponsors](/free-pro-team@latest/sponsors/getting-started-with-github-sponsors/about-github-sponsors)
- [About Enterprise accounts](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts)
- Conceptual sections within other articles
- "About security policies" in [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository#about-security-policies)
- "About maintenance mode" in [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode#about-maintenance-mode)

167
content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md Normal file
View File

@@ -0,0 +1,167 @@
---
title: Contents of a GitHub Docs article
shortTitle: Contents of an article
intro: '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.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
## About the structure of an article
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.
![Screenshot of article with title, intro, permissions, product callout, conceptual section, procedural section, and table of contents labeled.](/assets/images/contributing/illustration-of-article-contents.png)
## Titles
Titles fully describe what a page is about, and what someone will learn by reading it.
Titles can be challenging. Use these general guidelines to help create clear, helpful, and descriptive titles. The guidelines for each content type in this article provide more specific title rules.
### 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) 26 characters
- Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 29 characters
- Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 30 characters, ideally 20-25 characters
- Titles are consistent across a content type
- See specific guidelines for each content type
- Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products
- Use: "{% data variables.product.company_short %}'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
## 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.
- [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
## 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 someone 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 single permissions statement for multiple procedures: [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
## Tool switcher
Some articles have content that varies depending on what tool someone uses to complete a task, such as the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_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, see "[AUTOTITLE](/contributing/writing-for-github-docs/creating-tool-switchers-in-articles)".
## 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. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/conceptual-content-type)" in the content model.
## Referential content
Referential content provides structured information related to actively using a product or feature. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/referential-content-type)" in the content model.
## 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
- [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)
- [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-subdomain-isolation)
## Procedural content
Procedural content helps people complete tasks. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/procedural-content-type)" in the content model.
## Troubleshooting content
Troubleshooting content helps people avoid or work through errors. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/troubleshooting-content-type)" in the content model.
## 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
```markdown
### Further reading
- "[Article title](article-URL)”
- [External resource title](external-resource-URL) in External Resource Name
```

20
content/contributing/style-guide-and-content-model/index.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: Style guide and content model
intro: 'Learn about how we keep GitHub''s documentation consistent, easy to follow, and maintainable.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
children:
- /style-guide
- /about-the-content-model
- /contents-of-a-github-docs-article
- /about-topics
- /conceptual-content-type
- /referential-content-type
- /procedural-content-type
- /troubleshooting-content-type
- /release-note-content-type
- /quickstart-content-type
- /tutorial-content-type
- /about-combining-multiple-content-types
---

37
content/contributing/style-guide-and-content-model/procedural-content-type.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: Procedural content type
intro: 'Procedural content gives context on how a task fits into someone''s larger goal.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
Procedural content helps people complete a task from start to finish while they are using {% data variables.product.prodname_dotcom %}.
We create procedural articles and procedural sections within larger articles.
## How to write procedural articles
For the procedural content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#procedural-article-template)."
- Follow the style guidelines for procedural steps in "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#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
- [AUTOTITLE](/free-pro-team@latest/billing/managing-your-github-billing-settings/adding-information-to-your-receipts)
- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise)
- [AUTOTITLE](/actions/using-workflows/using-starter-workflows)

47
content/contributing/style-guide-and-content-model/quickstart-content-type.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Quickstart content type
intro: 'Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
Quickstarts enable people 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.
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.
## How to write a quickstart
For the quickstart template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#quickstart-article-template)."
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 someone 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 people that they are performing the correct actions.
- Troubleshooting (optional)
- If relevant troubleshooting content exists for the quickstart, provide links to it.
- Next steps
- Provide a quick recap of what has been accomplished in the quickstart as a means of transitioning to next steps.
- Include 2-3 actionable next steps that someone can 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 {% data variables.product.prodname_learning %}.
## 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
- [AUTOTITLE](/free-pro-team@latest/actions/quickstart)
- [AUTOTITLE](/free-pro-team@latest/discussions/quickstart)
- [Quickstart for GitHub Educators](/free-pro-team@latest/education/quickstart)

43
content/contributing/style-guide-and-content-model/referential-content-type.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: Referential content type
intro: 'Referential content provides detailed information that people need while they are actively using a feature.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
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 {% data variables.product.prodname_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
For the referential content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#referential-article-template)."
- 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: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-roles-for-organizations)
- For subjects with multiple elements to explain, use a table.
- Example: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permissions-for-each-role)
- 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: [AUTOTITLE](/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
- [AUTOTITLE](/get-started/using-github/keyboard-shortcuts)
- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
- [AUTOTITLE](/free-pro-team@latest/rest/reference/billing) in the REST API documentation
- [AUTOTITLE](/graphql/reference/mutations) in the GraphQL API documentation
- Referential sections within other articles
- "Supported languages" in [AUTOTITLE](/free-pro-team@latest/get-started/using-github/github-mobile#supported-languages-for-github-mobile)
- "Hardware considerations" in [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws#hardware-considerations)

21
content/contributing/style-guide-and-content-model/release-note-content-type.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: Release note content type
intro: 'Release notes enable readers to understand and prepare for the user-facing changes in each release of {% data variables.product.prodname_dotcom %}''s versioned enterprise products.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
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 {% data variables.product.prodname_dotcom %} features and functionality.
Writers source, edit, and publish release notes in collaboration with product DRIs, feature owners, and individual engineers at {% data variables.product.prodname_dotcom %}. For each individual release, we group release notes by predefined types.
We publish the release notes for [{% data variables.product.prodname_ghe_server %}](/enterprise-server@latest/admin/release-notes)(GHES) and [{% data variables.product.prodname_ghe_managed %}](/github-ae@latest/admin/release-notes)(GHAE) on {% data variables.product.prodname_docs %}, in the "Enterprise administrators" documentation set.
## Types of releases
{% data variables.product.prodname_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](/enterprise-server@latest/admin/overview/about-upgrades-to-new-releases) or [GHAE](/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 "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)".

10
content/contributing/writing-for-github-docs/style-guide.md → content/contributing/style-guide-and-content-model/style-guide.md
View File

@@ -4,6 +4,8 @@ intro: 'Follow this guide to make sure {% data variables.product.company_short %
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/writing-for-github-docs/style-guide
---
{% note %}
@@ -200,7 +202,7 @@ Headers must adequately describe the content under them. Follow the same guideli
Use H2 for headers, and H3 for subheaders. If the article has headers, the headers must start with an H2 level header and cannot skip header levels. There must be content between a header and subheader, such as an introduction. When referring to headers, surround the header name with quotation marks.
- **Use:** Under "User licenses," view your total licenses.
For more information, see the "[Content model](/contributing/writing-for-github-docs/content-model#titles)."
For more information, see the "[AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)."
## Images
@@ -693,7 +695,7 @@ Otherwise, follow standard American English punctuation rules. For more guidance
A set of release notes on {% data variables.product.prodname_docs %} tell readers about administrator- or user-facing changes to a versioned release of a product like {% data variables.product.prodname_ghe_server %} (GHES). Release notes appear in the [AUTOTITLE](/enterprise-server@latest/admin/release-notes).
A good release note is a few sentences that sequentially answer the reader's questions about the change. For more information, see [Content model for GitHub Docs](/contributing/writing-for-github-docs/content-model#release-notes).
A good release note is a few sentences that sequentially answer the reader's questions about the change. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/release-note-content-type).
Each release note in a set describes one of the following changes.
@@ -836,7 +838,7 @@ A release note for a known issue answers the following questions.
- To clarify actors and impact, avoid passive language when possible.
- To reduce repetition and unnecessary words, "now" is usually implied.
- If useful, include relevant links to GitHub Docs.
- Known issues are also a [type of content on GitHub Docs](/contributing/writing-for-github-docs/content-model#known-issues). If useful, write or link to more in-depth and contextually relevant content in the docs.
- Known issues are also a type of content on GitHub Docs. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/troubleshooting-content-type#known-issues)." If useful, write or link to more in-depth and contextually relevant content in the docs.
#### Examples of release notes for known issues
@@ -1383,7 +1385,7 @@ When specifying the access required to take an action, refer only to the role at
- **Use:** `People with write access to a repository can do X to the repository.`
- **Avoid:** `Organization owners and people with write access can do X to the repository.`
For more information about word choice for permissions statements, see "[Permissions statements](/contributing/writing-for-github-docs/content-model#permissions-statements)" in the content model.
For more information about word choice for permissions statements, see "[AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#permissions-statements)" in the content model.
### Prepositions

45
content/contributing/style-guide-and-content-model/troubleshooting-content-type.md Normal file
View File

@@ -0,0 +1,45 @@
---
title: Troubleshooting content type
intro: 'Troubleshooting content includes built-in errors we expect people to encounter, common problems reported to support, and situations people might encounter while completing tasks.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
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 {% data variables.product.prodname_dotcom %} 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 people's 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 {% data variables.product.prodname_dotcom %} has not yet prioritized fixing, and that are not explained in the product or by existing content on {% data variables.product.prodname_docs %}.
## How to write troubleshooting content
- Use any {% data variables.product.prodname_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 "[AUTOTITLE](/authentication/troubleshooting-ssh)."
## Title guidelines for troubleshooting content
- Troubleshooting FEATURE
- Error: ERROR NAME
- Known issues for PRODUCT
## Examples of troubleshooting content
- "[AUTOTITLE](/authentication/troubleshooting-ssh)"
- "[AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#troubleshooting-connectivity-through-a-load-balancer)"
- "[Known issues](/enterprise-server@3.7/admin/release-notes#3.7.8-known-issues)" in the {% data variables.product.prodname_ghe_server %} release notes
- "[AUTOTITLE](/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit)"

59
content/contributing/style-guide-and-content-model/tutorial-content-type.md Normal file
View File

@@ -0,0 +1,59 @@
---
title: Tutorial content type
intro: 'Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
---
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 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 {% data variables.product.prodname_dotcom %}. Tutorials can also help people validate whether the solution is appropriate for their needs.
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.
## How to write a tutorial
For the tutorial template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#tutorial-article-template)."
Contents of tutorials:
- Introduction
- Clarifies audience.
- Clearly states prerequisites and prior knowledge needed.
- States what someone will accomplish or build.
- Includes an example of a successful project.
- Does not include the expected amount of time that it may take someone to complete the task - this depends on the experience level of the person completing the tutorial.
- 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 people that they are performing the correct actions.
- Provide real examples.
- For example, do not tell someone 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 was 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 someone can take after completing the tutorial. Link off to other related information like:
- Projects on {% data variables.product.prodname_dotcom %} that illustrate the introduced concepts
- Relevant information on docs.github.com
- Relevant {% data variables.product.prodname_learning %}
- Relevant published talks, blog posts, or Community Forum series posts by Hubbers
## Title guidelines for tutorials
- Follow the title guidelines for procedural articles.
- Do not use "tutorial” or "guide” in the title.
## Examples of tutorials
Tutorials:
- [AUTOTITLE](/actions/managing-issues-and-pull-requests/adding-labels-to-issues)
- [AUTOTITLE](/actions/deployment/deploying-xcode-applications/installing-an-apple-certificate-on-macos-runners-for-xcode-development)
Language and framework guides:
- [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-nodejs)
- [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-python)
- [AUTOTITLE](/actions/publishing-packages/publishing-java-packages-with-maven)

16
content/contributing/syntax-and-versioning-for-github-docs/index.md
View File

@@ -1,16 +0,0 @@
---
title: Syntax and versioning for GitHub Docs
shortTitle: Syntax and versioning
intro: 'Learn about using Liquid, YAML, and Markdown to format and version GitHub''s documentation.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
children:
- /versioning-documentation
- /using-yaml-frontmatter
- /using-markdown-and-liquid-in-github-docs
- /changing-an-articles-title
- /configuring-redirects
- /creating-tool-switchers-in-articles
- /annotating-code-examples
---

2
content/contributing/syntax-and-versioning-for-github-docs/annotating-code-examples.md → content/contributing/writing-for-github-docs/annotating-code-examples.md
View File

@@ -6,6 +6,8 @@ product: '{% data reusables.contributing.product-note %}'
layout: inline
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/annotating-code-examples
---
## About code annotations

2
content/contributing/syntax-and-versioning-for-github-docs/changing-an-articles-title.md → content/contributing/writing-for-github-docs/changing-an-articles-title.md
View File

@@ -5,6 +5,8 @@ intro: "When it's necessary to change the title of an article, the name may need
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/changing-an-articles-title
---
## Changing the title of an article

2
content/contributing/syntax-and-versioning-for-github-docs/configuring-redirects.md → content/contributing/writing-for-github-docs/configuring-redirects.md
View File

@@ -4,6 +4,8 @@ intro: "If an article's title, version, or location changes, you can create a re
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/configuring-redirects
---
## About redirects

619
content/contributing/writing-for-github-docs/content-model.md
View File

@@ -1,619 +0,0 @@
---
title: Using the GitHub Docs content model
shortTitle: Content model
intro: 'The content model describes the structure and types of content that we publish.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
allowTitleToDifferFromFilename: true
---
## About the content model for {% data variables.product.prodname_docs %}
Our content model explains the purpose of each type of content we create within {% data variables.product.prodname_docs %}, and what to include when you write or update an article. We use a content model to ensure that our content consistently, clearly, and comprehensively communicates the information that people need to achieve their goals with {% data variables.product.prodname_dotcom %}.
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 {% data variables.product.prodname_docs %} over time. It is also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you are an open source contributor making your first commit or a writer on the {% data variables.product.prodname_dotcom %} staff 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 {% data variables.product.prodname_docs %} homepage, [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 {% data variables.product.prodname_dotcom %} concepts and practices. For example, the "CI/CD and DevOps" group includes top-level doc sets for {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, and {% data variables.product.prodname_pages %}.
#### Adding a doc set to the homepage
The goal of the homepage is to help people find information about the {% data variables.product.prodname_dotcom %} feature or product that they want to learn about. Every item added to 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 {% data variables.product.prodname_dotcom %} 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](/code-security)" top-level doc set, the "[Supply chain security](/code-security/supply-chain-security)," "[Security advisories](/code-security/security-advisories)," "[{% data variables.product.prodname_dependabot %}](/code-security/dependabot)," "[{% data variables.product.prodname_code_scanning_caps %}](/code-security/code-scanning)," and "[{% data variables.product.prodname_secret_scanning_caps %}](/code-security/secret-scanning)" categories are included because each of those categories are the entry point to {% data variables.product.prodname_dotcom %} products and features. "[Security overview](/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 {% data variables.product.prodname_dotcom %} product, feature, or core workflow. All top-level doc sets appear on the {% data variables.product.prodname_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 {% data variables.product.prodname_dotcom %} 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](/free-pro-team@latest/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 {% data variables.product.prodname_dotcom %} someone is using.
- Examples
- [AUTOTITLE](/organizations)
- [AUTOTITLE](/issues)
### Category
Categories are organized around a feature or a discrete set of tasks within a top-level doc set aligned with product themes. A category's subject is narrow enough that its contents are manageable and does not grow too large to use. Some categories appear on the 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.
#### 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
- [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github)
- [AUTOTITLE](/pull-requests/committing-changes-to-your-project)
#### Intros for categories
All categories have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. 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.
#### 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
- [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain)
- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise)
#### Intros for map topics
All map topics have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. 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 {% data variables.product.prodname_docs %}––while we use multiple content types, they are 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 information, 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
### Topics
Topics are used to filter articles and are searchable across the {% data variables.product.prodname_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 {% data variables.product.prodname_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 {% data variables.product.prodname_actions %}”
- Avoid: `Actions` in an article like "Introduction to {% data variables.product.prodname_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 {% data variables.product.prodname_dotcom %} 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? 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 or 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. People most often use conceptual content when they are learning about something new to them.
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
For the conceptual content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#conceptual-article-template)."
- 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 {% data variables.product.prodname_code_scanning %}"
- Avoid: "About scanning your code for vulnerabilities"
#### Examples of conceptual content
- Conceptual articles
- [About GitHub Sponsors](/free-pro-team@latest/sponsors/getting-started-with-github-sponsors/about-github-sponsors)
- [About Enterprise accounts](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts)
- Conceptual sections within other articles
- "About security policies" in [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository#about-security-policies)
- "About maintenance mode" in [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode#about-maintenance-mode)
### Referential
Referential content provides detailed information that people need while they are 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 {% data variables.product.prodname_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
For the referential content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#referential-article-template)."
- 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: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-roles-for-organizations)
- For subjects with multiple elements to explain, use a table.
- Example: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permissions-for-each-role)
- 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: [AUTOTITLE](/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
- [AUTOTITLE](/get-started/using-github/keyboard-shortcuts)
- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
- [AUTOTITLE](/free-pro-team@latest/rest/reference/billing) in the REST API documentation
- [AUTOTITLE](/graphql/reference/mutations) in the GraphQL API documentation
- Referential sections within other articles
- "Supported languages" in [AUTOTITLE](/free-pro-team@latest/get-started/using-github/github-mobile#supported-languages-for-github-mobile)
- "Hardware considerations" in [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws#hardware-considerations)
### Procedural
Procedural content helps people complete a task from start to finish while they are using {% data variables.product.prodname_dotcom %}. 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
For the procedural content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#procedural-article-template)."
- Follow the style guidelines for procedural steps in "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#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
- [AUTOTITLE](/free-pro-team@latest/billing/managing-your-github-billing-settings/adding-information-to-your-receipts)
- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise)
- [AUTOTITLE](/actions/learn-github-actions/using-starter-workflows)
### Release notes
Release notes enable readers to understand and prepare for the user-facing changes in each release of {% data variables.product.prodname_dotcom %}'s versioned enterprise products (e.g., {% data variables.product.prodname_ghe_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 {% data variables.product.prodname_dotcom %} features and functionality.
Writers source, edit, and publish release notes in collaboration with product DRIs, feature owners, and individual engineers at {% data variables.product.prodname_dotcom %}. For each individual release, we group release notes by predefined types.
We publish the release notes for [{% data variables.product.prodname_ghe_server %}](/enterprise-server@latest/admin/release-notes)(GHES) and [{% data variables.product.prodname_ghe_managed %}](/github-ae@latest/admin/release-notes)(GHAE) on {% data variables.product.prodname_docs %}, in the "Enterprise administrators" documentation set.
#### Types of releases
{% data variables.product.prodname_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](/enterprise-server@latest/admin/overview/about-upgrades-to-new-releases) or [GHAE](/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 "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide)".
### Troubleshooting
Troubleshooting content includes built-in errors we expect people 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 {% data variables.product.prodname_dotcom %} 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 people's 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 {% data variables.product.prodname_dotcom %} has not yet prioritized fixing, and that are not explained in the product or by existing content on {% data variables.product.prodname_docs %}.
#### How to write troubleshooting content
- Use any {% data variables.product.prodname_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 "[AUTOTITLE](/authentication/troubleshooting-ssh)."
#### Title guidelines for troubleshooting content
- Troubleshooting FEATURE
- Error: ERROR NAME
- Known issues for PRODUCT
#### Examples of troubleshooting content
- "[AUTOTITLE](/authentication/troubleshooting-ssh)"
- "[AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#troubleshooting-connectivity-through-a-load-balancer)"
- "[Known issues](/enterprise-server@3.7/admin/release-notes#3.7.8-known-issues)" in the {% data variables.product.prodname_ghe_server %} release notes
- "[AUTOTITLE](/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 is 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
- [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility)
- [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
- [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-github-account/upgrading-your-github-subscription)
- [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode)
### Quickstart
Quickstarts enable people 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. Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.
#### How to write a quickstart
For the quickstart template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#quickstart-article-template)."
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 someone 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 people that they are performing the correct actions.
- Troubleshooting (optional)
- If relevant troubleshooting content exists for the quickstart, provide links to it.
- Next steps
- Provide a quick recap of what has been accomplished in the quickstart as a means of transitioning to next steps.
- Include 2-3 actionable next steps that someone can 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 {% data variables.product.prodname_learning %}.
#### 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
- [AUTOTITLE](/free-pro-team@latest/actions/quickstart)
- [AUTOTITLE](/free-pro-team@latest/discussions/quickstart)
- [Quickstart for GitHub Educators](/free-pro-team@latest/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 {% data variables.product.prodname_dotcom %}. Tutorials can also help people validate whether the solution is appropriate for their needs.
#### How to write a tutorial
For the tutorial template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#tutorial-article-template)."
Contents of tutorials:
- Introduction
- Clarifies audience.
- Clearly states prerequisites and prior knowledge needed.
- States what someone will accomplish or build.
- Includes an example of a successful project.
- Does not include the expected amount of time that it may take someone to complete the task - this depends on the experience level of the person completing the tutorial.
- 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 people that they are performing the correct actions.
- Provide real examples.
- For example, do not tell someone 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 was 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 someone can take after completing the tutorial. Link off to other related information like:
- Projects on {% data variables.product.prodname_dotcom %} that illustrate the introduced concepts
- Relevant information on docs.github.com
- Relevant {% data variables.product.prodname_learning %}
- Relevant published talks, blog posts, or Community Forum series posts by Hubbers
#### Title guidelines for tutorials
- Follow the title guidelines for procedural articles.
- Do not use "tutorial” or "guide” in the title.
#### Examples of tutorials
Tutorials:
- [AUTOTITLE](/actions/managing-issues-and-pull-requests/adding-labels-to-issues)
- [AUTOTITLE](/actions/deployment/deploying-xcode-applications/installing-an-apple-certificate-on-macos-runners-for-xcode-development)
Language and framework guides:
- [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-nodejs)
- [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-python)
- [AUTOTITLE](/actions/publishing-packages/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 {% data variables.product.prodname_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.
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
1. Product callout (conditional)
1. Intro
1. Permissions statement (conditional)
1. Tool switcher (conditional)
1. Table of contents
1. Conceptual content
1. Referential content
1. Prerequisites
1. Procedural content
1. Troubleshooting content
1. Further reading (conditional)
![Screenshot of article with title, intro, permissions, product callout, conceptual section, procedural section, and table of contents labeled.](/assets/images/contributing/illustration-of-article-contents.png)
### Titles
Titles fully describe what a page is about, and what someone will learn by reading it.
Titles can be challenging. Use these general guidelines to help create clear, helpful, and descriptive titles. The guidelines for each content type in this article provide more specific title rules.
#### 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) 26 characters
- Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 29 characters
- Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 30 characters, ideally 20-25 characters
- Titles are consistent across a content type
- See specific guidelines for each content type
- Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products
- Use: "{% data variables.product.company_short %}'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
### 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.
- [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
### 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 someone 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 single permissions statement for multiple procedures: [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
### Tool switcher
Some articles have content that varies depending on what tool someone uses to complete a task, such as the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_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](https://github.com/github/docs/blob/main/contributing/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
- [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)
- [AUTOTITLE](/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
```markdown
### Further reading
- "[Article title](article-URL)”
- [External resource title](external-resource-URL) in External Resource Name
```

2
content/contributing/writing-for-github-docs/creating-screenshots.md
View File

@@ -101,7 +101,7 @@ To meet the needs of more users, screenshots must:
- Be accompanied by complete instructions in the procedural step, 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. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#alt-text)."
- Have alt text that describes the content of the image and the appearance of its highlighting, if any. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#alt-text)."
- Be clear and crisp, with text and UI elements as legible as possible.
### Visual style

4
content/contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles.md → content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md
View File

@@ -5,6 +5,8 @@ intro: 'You can use a tool switcher to show how to complete tasks using specific
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles
---
## About tool switchers
@@ -35,7 +37,7 @@ Tool tags are Liquid tags that wrap content specific to a tool. <!--For more inf
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 by specifying a `defaultTool:` property in the article's frontmatter. For more information, see the [content README](https://github.com/github/docs/blob/main/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 "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#links-to-a-specific-tool)."
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 "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#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.

15
content/contributing/writing-for-github-docs/index.md
View File

@@ -1,18 +1,25 @@
---
title: Writing for GitHub Docs
shortTitle: Writing for GitHub Docs
intro: 'Learn about writing for {% data variables.product.prodname_docs %}, our content model, and how to follow our style guide.'
intro: 'Learn about writing for {% data variables.product.prodname_docs %}.'
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
children:
- /style-guide
- /content-model
- /about-githubs-documentation-philosophy
- /writing-content-to-be-translated
- /content-design-principles
- /versioning-documentation
- /using-markdown-and-liquid-in-github-docs
- /using-yaml-frontmatter
- /using-videos-in-github-docs
- /creating-reusable-content
- /content-design-principles
- /creating-screenshots
- /creating-tool-switchers-in-articles
- /configuring-redirects
- /changing-an-articles-title
- /annotating-code-examples
- /templates
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs
---

14
content/contributing/writing-for-github-docs/templates.md
View File

@@ -8,7 +8,7 @@ versions:
## Conceptual article template
Use the content model for full instructions and examples on how to write conceptual content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#conceptual)."
Use the content model for full instructions and examples on how to write conceptual content. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/conceptual-content-type)."
```yaml
{% raw %}---
@@ -56,7 +56,7 @@ Optionally, include a bulleted list of related articles the user can reference t
## Referential article template
Use the content model for full instructions and examples on how to write referential content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#referential)."
Use the content model for full instructions and examples on how to write referential content. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/referential-content-type)."
```yaml
{% raw %}---
@@ -104,7 +104,7 @@ Optionally, include a bulleted list of related articles the user can reference t
## Procedural article template
Use the content model for full instructions and examples on how to write procedural content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#procedural)."
Use the content model for full instructions and examples on how to write procedural content. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/procedural-content-type)."
```yaml
{% raw %}---
@@ -131,7 +131,7 @@ Remove these comments from your article file when you're done writing
{% comment %}
Include prerequisite information or specific permissions information here.
Then write procedural steps following the instructions in https://docs.github.com/contributing/writing-for-github-docs/style-guide#procedural-steps.
Then write procedural steps following the instructions in https://docs.github.com/contributing/style-guide-and-content-model/style-guide#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. Look at the source file for a procedure located in the same area of the user interface to find reusables.
{% endcomment %}
@@ -152,7 +152,7 @@ Optionally, include a bulleted list of related articles the user can reference t
## Quickstart article template
Use the content model for full instructions and examples on how to write quickstarts. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#quickstart)."
Use the content model for full instructions and examples on how to write quickstarts. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/quickstart-content-type)."
```yaml
{% raw %}---
@@ -216,7 +216,7 @@ Provide a quick recap of what has been accomplished in the quick start as a mean
## Tutorial article template
Use the content model for full instructions and examples on how to write tutorials. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#tutorial)."
Use the content model for full instructions and examples on how to write tutorials. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/tutorial-content-type)."
```yaml
{% raw %}---
@@ -287,7 +287,7 @@ Include a bulleted list of tutorials or articles the user can reference to exten
## Language guides for GitHub Actions
Use the content model for full instructions and examples on how to write for {% data variables.product.prodname_docs %}. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model)."
Use the content model for full instructions and examples on how to write for {% data variables.product.prodname_docs %}. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model)."
```yaml
{% raw %}---

10
content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md → content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md
View File

@@ -5,6 +5,8 @@ intro: 'You can use Markdown and Liquid to format content, create reusable conte
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs
---
## About using Markdown and Liquid in {% data variables.product.prodname_docs %}
@@ -51,7 +53,7 @@ This content is displayed on the {% data variables.product.prodname_docs %} site
Callouts highlight important information that users need to know. We use standard formatting and colors for different types of callouts: notes, warnings, and danger notices. Use Liquid tags before and after the text you’d like included in the callout box.
For information on when to use callout tags, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#callouts)."
For information on when to use callout tags, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#callouts)."
### Example usage of a callout
@@ -147,7 +149,7 @@ If you're referencing an Octicon that appears in the UI, identify whether the Oc
- Some Octicons used as labels have dynamic `aria-label` elements that change based on the state of the UI element or a user input. For example, when someone has two security policies-`Policy A` and `Policy B`-their UI will show two trash Octicons labelled `{% octicon "trash" aria-label="Delete Policy A" %}` and `{% octicon "trash" aria-label="Delete Policy B" %}`. For dynamic `aria-label` elements, since we can't document the exact `aria-label` that people will encounter, describe the Octicon and a placeholder example of the label (for example, `"{% octicon "trash" aria-label="The trash icon, labelled 'Delete YOUR-POLICY-NAME'." %}"`). This will help people identify both the Octicon and how it is labelled, and give context for collaborating with people who are visually describing the Octicon.
- 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 (for example, `"{% 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 "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#tables)."
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 "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#tables)."
### Example usage of Octicons
@@ -314,7 +316,7 @@ Every row of a table in the {% data variables.product.prodname_docs %} must star
## 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 {% raw %}`{% rowheaders %} {% endrowheaders %}`{% endraw %}. For more information on using markup for tables, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#use-proper-markup-for-row-and-column-headers)."
If you create a table where the first column contains headers for the table rows, wrap your table in the Liquid tag {% raw %}`{% rowheaders %} {% endrowheaders %}`{% endraw %}. For more information on using markup for tables, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#use-proper-markup-for-row-and-column-headers)."
### Example table with row headers
@@ -381,7 +383,7 @@ and when viewed on {% data variables.product.prodname_ghe_server %} docs, the ve
/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply
```
For more information about links, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#links)."
For more information about links, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#links)."
### Permalinks

4
content/contributing/writing-for-github-docs/using-videos-in-github-docs.md
View File

@@ -75,7 +75,7 @@ Use videos that explain the value of the procedure or concept that they are show
## 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 "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#alt-text)." Do not use videos that just show a task without explaining or elaborating on the procedure. Videos must be useful and relevant, which includes staying accurate over time.
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 "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#alt-text)." Do not use videos that just show a task without explaining or elaborating on the procedure. Videos must be useful and relevant, which includes staying accurate over time.
## Accessibility requirements
@@ -144,7 +144,7 @@ product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE
## Titles for videos
Titles should be descriptive and follow the guidelines for titles in "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#titles)."
Titles should be descriptive and follow the guidelines for titles in the content model. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#titles)."
## Versioning

4
content/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter.md → content/contributing/writing-for-github-docs/using-yaml-frontmatter.md
View File

@@ -5,6 +5,8 @@ intro: 'You can use YAML frontmatter to define versioning, add metadata, and con
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter
---
## About YAML frontmatter
@@ -286,7 +288,7 @@ As an alternative, you can change the single quotes surrounding the frontmatter
## Autogenerated mini TOCs
Every article displays a mini table of contents (TOC), which is an autogenerated "In this article" section that includes links to all `H2`s in the article. Only `H2` headers are included in the mini TOCs. If an article uses `H3` or `H4` headers to divide information in a way that only certain sections are relevant to a particular task, you can help people navigate to the content most relevant to them by using a [sectional TOC](/contributing/writing-for-github-docs/style-guide#sectional-tocs).
Every article displays a mini table of contents (TOC), which is an autogenerated "In this article" section that includes links to all `H2`s in the article. Only `H2` headers are included in the mini TOCs. If an article uses `H3` or `H4` headers to divide information in a way that only certain sections are relevant to a particular task, you can help people navigate to the content most relevant to them by using a [sectional TOC](/contributing/style-guide-and-content-model/style-guide#sectional-tocs).
You can use the [`showMiniToc`](#showminitoc) frontmatter value, set to `false`, to prevent the mini TOC from showing up for an article.

2
content/contributing/syntax-and-versioning-for-github-docs/versioning-documentation.md → content/contributing/writing-for-github-docs/versioning-documentation.md
View File

@@ -4,6 +4,8 @@ intro: '{% data variables.product.prodname_docs %} uses YAML frontmatter and liq
product: '{% data reusables.contributing.product-note %}'
versions:
feature: 'contributing'
redirect_from:
- /contributing/syntax-and-versioning-for-github-docs/versioning-documentation
---
On {% data variables.product.prodname_docs %}, we provide versions of our documentation that reflect the differences in UI and functionality across {% data variables.product.company_short %}'s major product offerings. Contributors can use versioning syntax to scope content to a specific product offering.

2
content/contributing/writing-for-github-docs/writing-content-to-be-translated.md
View File

@@ -9,7 +9,7 @@ versions:
## About writing content that is translation-friendly
Use the following guidelines to ensure the content you create can be successfully translated. For more information, see "[Style guide](/contributing/writing-for-github-docs/style-guide)."
Use the following guidelines to ensure the content you create can be successfully translated. For more information, see "[Style guide](/contributing/style-guide-and-content-model/style-guide)."
- Use examples that are generic and can be understood by most people.
- Avoid examples that are controversial or culturally specific to a group.