Sobre os alternadores de ferramentas
Em alguns artigos, escrevemos um conteúdo adaptado a diferentes ferramentas (a interface do usuário do GitHub, a GitHub CLI, o GitHub Desktop, o cURL, o Codespaces, o VS Code, a API do GraphQL etc.) O alternador de ferramentas permite que as pessoas selecionem uma ferramenta para ver apenas o conteúdo relevante a ela, pois as ferramentas podem ter informações conceituais ou de procedimentos diferentes.
As pessoas podem usar o alternador de ferramentas de duas maneiras ao ler a documentação.
-
Explorar - Para tarefas que podem ser concluídas com ferramentas diferentes, o seletor de ferramentas sinaliza para as pessoas que há várias maneiras de realizar uma tarefa. Por exemplo, usando a GitHub CLI ou o GitHub Desktop, em vez da interface do usuário do GitHub.
-
Direto ao ponto - Quando a pessoa sabe como quer realizar uma tarefa e não precisa ver opções adicionais, o seletor de ferramentas remove o conteúdo menos relevante, para que a pessoa possa encontrar exatamente o que precisa.
Como usar tags de ferramentas
Você pode adicionar seletores de ferramentas a um artigo usando tags de ferramenta no Markdown. As tags de ferramentas são tags do Liquid que encapsulam o conteúdo que você quer mostrar em uma guia específica de alternador de ferramenta.
Por exemplo, o bloco de código a seguir mostra o conteúdo de três ferramentas diferentes.
{% vscode %}
This content is specific to Visual Studio Code.
{% endvscode %}
{% visualstudio %}
This content is specific to Visual Studio.
{% endvisualstudio %}
{% jetbrains %}
This content is specific to JetBrains IDEs.
{% endjetbrains %}
Por padrão, a primeira tag de ferramenta usada no Markdown é selecionada para um artigo. Você pode definir uma ferramenta padrão diferente para um artigo especificando uma propriedade defaultTool: na matéria frontal do artigo. Para obter mais informações, confira o LEIAME do conteúdo.
Você também pode criar um link para um artigo com uma ferramenta específica selecionada adicionando ?tool=TOOLNAME ao final do link. Para saber mais, confira Guia de estilo.
Inclua, no máximo, oito ferramentas diferentes em um artigo. A inclusão de mais ferramentas faz com que as guias do alternador de ferramentas se sobreponham ao sumário de um artigo, o que impede as pessoas de usar o alternador de ferramentas ou o sumário. É improvável que você precise incluir oito ferramentas separadas em um artigo. Em geral, planeje usar o mínimo possível de ferramentas separadas em um artigo.
Quando usar tags de ferramentas
Usaremos tags de ferramentas somente se um artigo precisar ter informações específicas da ferramenta para ajudar as pessoas a realizar as tarefas.
Não use o alternador de ferramentas apenas para mostrar exemplos em linguagens diferentes. Só use o alternador de ferramentas somente se as tarefas ou os conceitos descritos em um artigo mudarem com base na ferramenta usada.
Como adicionar novas ferramentas
O GitHub Docs documenta e mantém marcas de ferramenta para produtos do GitHub, ferramentas desenvolvidas pelo GitHub e extensões selecionadas de terceiros desenvolvidas em colaboração com a GitHub.
Novas ferramentas só são adicionadas quando são a única maneira de documentar com precisão algo para uma necessidade específica do usuário. Se um redator determinar que a adição de uma nova ferramenta é a única maneira de documentar algo com precisão, ele precisará propor a nova ferramenta em um plano de design de conteúdo. Quem examina o plano de design de conteúdo deve considerar todas as formas alternativas de atender às necessidades de documentação sem adicionar uma nova ferramenta. Se uma nova ferramenta for a única maneira de criar uma documentação precisa, a nova ferramenta deverá ser adicionada. Se houver uma solução alternativa de conteúdo que não adicione uma nova ferramenta, essa opção deverá ser usada.
Para adicionar uma nova ferramenta, adicione uma entrada ao objeto allTools no arquivo lib/all-tools.js como um par chave-valor. A chave é a tag que você usa para se referir à ferramenta no artigo, e o valor é como a ferramenta será identificada no seletor de ferramentas na parte superior do artigo. Por exemplo, vscode: 'Visual Studio Code'.
Adicione as novas ferramentas em ordem alfabética.