From 9a1f88bcb90e2e99c5c280eb47cc3f9810a2bcc0 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 3 Oct 2023 17:43:36 -0700 Subject: [PATCH] Update tool tag docs (#43688) Co-authored-by: hubwriter --- .../creating-tool-switchers-in-articles.md | 4 +++- .../using-markdown-and-liquid-in-github-docs.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md b/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md index f787ff5022a7..34eca772f3bb 100644 --- a/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md +++ b/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md @@ -43,6 +43,8 @@ Only include a maximum of eight different tools in an article. Including more to ## 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. +{% data variables.product.prodname_docs %} documents and maintains tool tags for {% data variables.product.prodname_dotcom %} products, {% data variables.product.prodname_dotcom %}-developed tools, and select third-party extensions. + +New tools are only added when they are the only way to accurately document something for a specific user need. If a writer determines that adding a new tool is the only way to accurately document something, they need to propose the new tool in a content design plan. Whoever reviews the content design plan should consider any alternative ways to address the documentation needs 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 the [`lib/all-tools.js`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.js) file as a key-value pair. Add new tools in alphabetical order. diff --git a/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md b/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md index aeaf00888b32..654b4d6c6b2a 100644 --- a/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md +++ b/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md @@ -194,7 +194,9 @@ You can define a default platform in an article's YAML frontmatter. For more inf ## Tool tags -We occasionally need to write documentation for different tools ({% data variables.product.prodname_dotcom %} UI, {% data variables.product.prodname_cli %}, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_github_codespaces %}, curl, Visual Studio Code, JetBrains IDEs, {% data variables.product.prodname_importer_proper_name %} CLI, GraphQL API). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool. +We occasionally need to write documentation that has different instructions for different tools. For example, the {% data variables.product.prodname_dotcom %} UI, {% data variables.product.prodname_cli %}, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_github_codespaces %}, and Visual Studio Code might be able to accomplish the same task using different steps. We use tool tags to control what information is displayed for each tool. + +{% data variables.product.prodname_docs %} maintains tool tags for {% data variables.product.prodname_dotcom %} products and selected third-party extensions. See the [`all-tools.js`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.js) object in the `github/docs` repository for a list of all supported tools. On rare occasions, we will add new tools. Before adding a new tool, read "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles)." To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](https://github.com/github/docs/blob/main/src/tools/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, and the value is how the tool will be identified on the tool picker at the top of the article.