Add content model for the tool switcher (#31393)

contributing/content-markup-reference.md

@@ -129,9 +129,11 @@ You can define a default platform in the frontmatter. For more information, see
 
 ## Tool tags
 
-We occasionally need to write documentation for different tools (GitHub UI, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, GitHub Enterprise Importer CLI, GraphQL API). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool. To modify the list of possible tools, edit [`lib/all-tools.js`](../lib/all-tools.js).
+We occasionally need to write documentation for different tools (GitHub UI, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, GitHub Enterprise Importer CLI, GraphQL API). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool.
 
-To add a new tool, add an entry to the `allTools` object in `lib/all-tools.js` as a key-value pair. The key is the tag you'll use to refer to the tool in the article, the value is how the tool will be identified on the tool picker at the top of the article.
+On rare occasions, we will add new tools. Before adding a new tool, read the [tool switcher content model](./tool-switcher.md). To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](../lib/all-tools.js) as a key-value pair. The key is the tag you'll use to refer to the tool in the article, the value is how the tool will be identified on the tool picker at the top of the article.
+
+You can define a default tool in the frontmatter. For more information, see the [content README](../content/README.md#defaulttool).
 
 ### Usage
 
@@ -223,8 +225,6 @@ These instructions are pertinent to javascript users.
 {% endjavascript %}
 ```
 
-You can define a default tool in the frontmatter. For more information, see the [content README](../content/README.md#defaulttool).
-
 ## Reusable and variable strings of text
 
 Reusable strings (commonly called content references or conrefs) contain content that’s used in more than one place in our documentation and allow us to change the content in a single location rather than every place the string appears.

contributing/content-model.md

@@ -374,13 +374,14 @@ Within an article, there is a standard order of content sections. Every article
 2. Product callout (conditional)
 3. Intro
 4. Permissions statement (conditional)
-5. Table of contents
+5. Tool switcher (conditional)
-6. Conceptual content
+6. Table of contents
-7. Referential content
+7. Conceptual content
-8. Prerequisites
+8. Referential content
-9. Procedural content
+9. Prerequisites
-10. Troubleshooting
+10. Procedural content
-11. Further reading (conditional)
+11. Troubleshooting
+12. Further reading (conditional)
 
 Here's what some of these elements look like rendered in an article.
 
@@ -441,6 +442,10 @@ Occasionally, it's relevant to mention required permissions in conceptual conten
 - Article with separate permissions statements for each procedure: [Upgrading your GitHub subscription](https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-your-github-subscription)
 - Article with single permissions statement for multiple procedures: [Enforcing repository management policies in your enterprise account](https://docs.github.com/en/github/setting-up-and-managing-your-enterprise/enforcing-repository-management-policies-in-your-enterprise-account)
 
+### Tool switcher
+
+Some articles have content that varies depending on what tool someone uses to complete a task, such as the GitHub CLI or GitHub Desktop. For most content, the same conceptual or procedural information will be accurate for multiple tools. However, if the only way to make information clear and accurate is by distinguishing content by tool, use the tool switcher. Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts change based on what tool someone uses. For more information on using the tool switcher, see the [tool switcher content model](./tool-switcher.md).
+
 ### Table of contents
 Tables of contents are automatically generated. For more information see "[Autogenerated mini-TOCs](https://github.com/github/docs/tree/main/content#autogenerated-mini-tocs)."
 

contributing/tool-switcher.md

@@ -0,0 +1,31 @@
+# Tool switcher
+
+In some articles, we write content tailored to different tools (GitHub UI, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, GitHub Enterprise Importer CLI, GraphQL API, etc.) Tools may have different conceptual or procedural information. People can select a tool to see only the content that is relevant to the tool. People can use the tool switcher in two ways when reading the docs.
+
+**Exploring**
+For tasks that can be completed with different tools, the tool switcher signals to people that there are multiple ways a task can be done (like using the CLI or Desktop, instead of the UI).
+
+**Getting to the point**
+When someone knows how they want to do a task and doesn’t need to see additional options, the tool switcher removes less relevant content, so they can find exactly what they need.
+
+We use tool tags to demarcate information for each tool. On rare occasions, we will add new tools.
+
+## Tool tags
+Tool tags are a key value pair. The key is the tag you use to refer to the tool in the article and the value is how the tool will be identified on the tool picker at the top of the article. The existing tools are in [`lib/all-tools.js`](../lib/all-tools.js).
+
+### When to use tool tags
+We only use tool tags if an article must have tool-specific information to help people accomplish their tasks. Just because multiple tools exist for a procedure does not mean we should document each tool individually. If the conceptual information behind a task or the procedural steps for accomplishing a task are different, and we want people to be able to accomplish the task with multiple tools, we use tool tags to present the relevant information in an article.
+
+Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts described in an article change based on what tool someone uses.
+
+### How to use tool tags
+Tool tags are Liquid tags that wrap content specific to a tool. For more information on using tool tags in an article, see the [content markup reference](./content-markup-reference.md#tool-tags).
+
+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.
+
+Tool tags are displayed alphabetically. You can define a default tool for an article in the article's frontmatter. For more information, see the [content README](../content/README.md#defaulttool).
+
+## Adding new tools
+If a writer determines that adding a new tool is the only way to accurately document something, they should explain their reasoning in the content planning stage. Whoever reviews content plan should consider if there are any alternative ways to address the documentation need without adding a new tool. If a new tool is the only way to create accurate documentation, the new tool should be added. If there is an alternative content solution that does not add a new tool, that option should be used.
+
+To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](../lib/all-tools.js) as a key-value pair. Add new tools in alphabetical order.