Sobre tópicos

Os tópicos são usados para filtrar artigos e podem ser pesquisados no site do GitHub Docs. Para alguns layouts, como páginas de aterrissagem ou guias, as pessoas podem selecionar os artigos exibidos filtrando os tópicos. Use essas diretrizes para ajudar a escolher os tópicos que serão adicionados à matéria frontal de um artigo. Para obter mais informações sobre como adicionar tópicos a um artigo, confira "Tópicos" e, para ver uma lista de todos os tópicos permitidos, confira allowed-topics.

Tópicos para todos os tipos de conteúdo

• Todos os artigos devem ter, pelo menos, um tópico
• Use substantivos como tópicos
• Os tópicos ajudam as pessoas a agrupar o conteúdo de maneira significativa
  • Quando possível, use tópicos mais específicos que sejam relevantes e não apenas tópicos amplos. Por exemplo, REST ou GraphQL em vez de API
  • Verifique se os tópicos sobre artigos semelhantes são consistentes para que as pessoas que filtram o conteúdo por um tópico obtenham todos os artigos relevantes. Por exemplo, todos os artigos sobre CI devem ter o tópico CI, além de tópicos mais específicos
  • Evite tópicos ambíguos. Por exemplo, talvez Actions não seja um tópico útil no produto Actions, pois ele pode se referir ao produto GitHub Actions ou ao elemento do produto chamado ação
• Os tópicos adicionam valor e não replicam o título, o tipo nem a categoria do artigo
  • Por exemplo, no produto Actions, Actions não agrega valor, pois alguém que esteja nessa seção da documentação já saberá que está examinando a documentação do Actions
• Use Fundamentals para artigos relacionados aos principais conceitos de uma área de produto.
  • Use: Fundamentals em um artigo como “Introdução ao GitHub Actions”
  • Evite: Actions em um artigo como "Introdução ao GitHub Actions"
• As abreviações comumente reconhecidas podem ser usadas, mas as abreviações obscuras ou ambíguas devem ser evitadas
  • Use CI em vez de Continuous integration
  • Evite: AS em vez de Advanced Security
• Use as formas curtas de nomes de produtos do GitHub
  • Use Actions em vez de GitHub Actions

Lista de verificação para escolha de tópicos

Considere estas perguntas para ajudar a escolher os tópicos para um artigo. Nem todos os artigos terão um tópico para cada item da lista de verificação.

• Qual é o recurso ou a área do produto?
  • Exemplo: Enterprise O artigo trata de um sub-recurso (a menos que o nome do produto corresponda ao nome do recurso)?
  • Exemplo: Dependabot
• O recurso faz parte de um programa restrito?
  • Exemplo: Advanced Security
• Qual elemento do recurso ou do produto é o artigo?
  • Exemplo: Organizations
• Qual é a finalidade geral do artigo?
  • Exemplo: Permissions
• Quais linguagens de programação, gerenciadores de pacotes ou ecossistemas o artigo aborda explicitamente? Só inclua esses tópicos se isso agregar valor a alguém que filtra a documentação, não apenas se um artigo listar as linguagens compatíveis, os gerenciadores de pacotes ou os ecossistemas.
  • Exemplo: Ruby