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 alternador 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.
Chegando ao ponto Quando alguém sabe como deseja realizar uma tarefa e não precisa ver opções adicionais, o alternador de ferramentas remove o conteúdo menos relevante, para que a pessoa possa encontrar exatamente o que precisa.
Como usar tags de ferramentas
Usamos tags de ferramentas para dividir as informações de cada ferramenta. Em raras ocasiões, adicionaremos novas ferramentas.
As tags de ferramentas são 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. As ferramentas existentes estão no repositório lib/all-tools.js do GitHub Docs.
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. Se as informações conceituais ou as etapas de procedimentos de uma tarefa são consideravelmente diferentes conforme a ferramenta usada e desejamos que as pessoas possam realizar a tarefa com diferentes ferramentas, usamos tags de ferramentas para apresentar as informações relevantes em um artigo.
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 usar tags de ferramentas
As tags de ferramentas são tags do Liquid que encapsulam o conteúdo específico de uma ferramenta.
Coloque as ferramentas em ordem alfabética. Por padrão, a primeira tag de ferramenta será 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 obter mais informações, 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.
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. Adicione as novas ferramentas em ordem alfabética.