Splitting up the content model (#42868)

Co-authored-by: Ethan Palm <[email protected]>

Author: guntrip

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

@@ -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.

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

@@ -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.

content/contributing/index.md

@@ -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
 ---

content/contributing/style-guide-and-content-model/about-combining-multiple-content-types.md

@@ -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)

content/contributing/style-guide-and-content-model/about-the-content-model.md

@@ -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.

content/contributing/style-guide-and-content-model/about-topics.md

@@ -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`