Sobre o modelo de conteúdo

O modelo de conteúdo descreve a estrutura e os tipos de conteúdo que publicamos.

Neste artigo

Nosso modelo de conteúdo explica a finalidade de cada tipo de conteúdo que criamos no GitHub Docs e o que incluir ao escrever ou atualizar um artigo. Usamos um modelo de conteúdo para garantir que o conteúdo comunique de maneira consistente, clara e abrangente as informações de que as pessoas precisam para atingir suas metas com o GitHub.

Usamos esses tipos em todos os conjuntos de documentação para fornecer uma experiência de usuário consistente, qualquer tipo de conteúdo se aplica a qualquer produto ou público-alvo. Nossos tipos de conteúdo evoluem ao longo do tempo, e adicionamos novos tipos conforme necessário. Só publicamos conteúdo que siga o modelo.

A consistência ajuda as pessoas a formar modelos mentais da documentação e a entender como encontrar as informações necessárias à medida que retornam ao GitHub Docs ao longo do tempo. Também é mais eficiente manter e atualizar um conteúdo consistente, tornando mais fácil e rápido contribuir com a documentação, seja você um colaborador de código aberto fazendo seu primeiro commit ou um redator da equipe do GitHub documentando um produto totalmente novo.

Estrutura do conteúdo

A documentação é organizada em vários níveis de hierarquia em nosso site.

  • Conjunto de documentação de nível superior
    • Categorias
      • Tópicos de mapa
        • Artigos
      • Artigos
    • Artigos

Organizar o conteúdo é um equilíbrio entre fazer agrupamentos específicos que ajudam as pessoas a encontrar o que estão procurando e limitar as camadas de hierarquia pelas quais as pessoas devem navegar. Hierarquias profundas com muitos tópicos de mapa aninhados juntos podem dificultar a localização de artigos específicos. Hierarquias amplas com muitas categorias ou artigos no mesmo nível tornam difícil para as pessoas avaliarem e decidirem o que desejam selecionar.

Conteúdo da home page

A home page do GitHub Docs, docs.github.com, destaca os tópicos mais importantes que as pessoas desejam encontrar. Limitamos o número de conjuntos de documentação na home page para que as pessoas possam encontrar informações e a home page não fique superlotada e difícil de pesquisar.

A home page inclui todos os conjuntos de documentação de nível superior e algumas categorias. O conteúdo da home page é organizado em torno de conceitos e práticas do GitHub. Por exemplo, o grupo "CI/CD e DevOps" inclui conjuntos de documentação de nível superior do GitHub Actions, do GitHub Packages e do GitHub Pages.

Como adicionar um conjunto de documentação à home page

O objetivo da home page é ajudar as pessoas a encontrar informações sobre o recurso ou o produto do GitHub sobre o qual elas desejam aprender. Cada item adicionado à home page dilui a capacidade de descoberta de todos os outros itens, portanto, limitamos o número de conjuntos de documentação incluídos na home page.

Se um novo conjunto de documentação de nível superior for criado, ele será adicionado à home page.

Se uma categoria servir como ponto de partida para uso de um produto ou de um recurso do GitHub, ela poderá ser adicionada à home page.

Por exemplo, no agrupamento "Segurança" na home page, além do conjunto de documentação de nível superior "Segurança de código", as categorias "Segurança da cadeia de fornecedores", "Avisos de segurança", "Dependabot", "Code scanning" e "Secret scanning" são incluídas, porque cada uma dessas categorias é o ponto de entrada de produtos e recursos do GitHub. A seção "Visão geral de segurança" não está incluída na home page porque fornece informações adicionais de uso dos produtos de segurança de código e não é uma introdução a um produto ou a um recurso.

Conjunto de documentação de nível superior

Os conjuntos de documentação de nível superior são organizados em torno de um produto, um recurso ou um fluxo de trabalho principal do GitHub. Todos os conjuntos de documentação de nível superior são exibidos na home page do GitHub Docs. Você só deverá criar um conjunto de documentação de nível superior quando houver um grande volume de conteúdo a ser contido no novo conjunto de documentação, várias categorias que serão divididas em tópicos de mapa e o tópico se aplicar a produtos, recursos ou tipos de contas. Se o conteúdo puder se enquadrar em qualquer conjunto de documentação de nível superior que já existe, provavelmente, ele pertencerá a esse conjunto de documentação existente.

  • Os conjuntos de documentação de nível superior têm aproximadamente igual importância entre si (cada um é centralizado em um produto ou em um recurso principal do GitHub).
  • A maioria dos conjuntos de documentação de nível superior tem um layout da página de aterrissagem, a menos que haja uma exceção significativa. Por exemplo, o conjunto de documentação "Política do site" não tem guias nem artigos de procedimentos como outros conjuntos de documentação, ou seja, ele não usa um layout de página de aterrissagem.
  • Os conjuntos de documentos de nível superior podem conter uma combinação de categorias, tópicos de mapa ou artigos.

Títulos para conjuntos de documentação de nível superior

Categoria

As categorias são organizadas em torno de um recurso ou de um conjunto discreto de tarefas em um conjunto de documentação de nível superior alinhado com temas do produto. O assunto de uma categoria é pequeno o suficiente para que o conteúdo seja gerenciável e não fique muito grande para ser usado. Algumas categorias são exibidas na home page.

  • Em geral, as categorias começam pequenas e crescem com o produto.
  • Categorias podem conter tópicos de mapa para subdividir o conteúdo em torno de tarefas ou percursos de usuário mais específicos.
  • Use artigos de procedimentos longos para agrupar partes relacionadas do conteúdo e manter os artigos da categoria simplificados.
  • Quando as categorias tiverem mais de dez artigos, considere a possibilidade de dividir o conteúdo em tópicos de mapa ou em categorias adicionais.
  • Categorias podem conter uma mistura de tópicos ou artigos de mapa.

Títulos para categorias

Introduções de categorias

Todas as categorias têm introduções. As introduções devem consistir em uma frase longa e geral ou de alto nível o suficiente para serem escaladas com as alterações futuras do produto. Se você alterar a estrutura de uma categoria de maneira significativa, verifique se são necessárias atualizações na introdução.

Tópico de mapa

Os tópicos de mapa introduzem uma seção de uma categoria, agrupando artigos em uma categoria em torno de fluxos de trabalho ou assuntos mais específicos que fazem parte da tarefa maior da categoria.

Os tópicos de mapa contêm, pelo menos, dois artigos. Quando os tópicos de mapa têm mais de oito artigos, pode ser útil considerar a divisão do conteúdo em tópicos de mapa mais específicos.

Em geral, evite ter um tópico de mapa dentro de um tópico de mapa, a menos que seja a melhor maneira de atender a uma necessidade específica do usuário.

Títulos para tópicos de mapa

  • Baseados em tarefa (começam com a estrutura Como + verbo).
  • Descrevem uma tarefa mais específica dentro do fluxo de trabalho maior da categoria em que ela se encontra.
  • Gerais ou de alto nível o suficiente para ser escalados com adições futuras ao produto.
  • Os títulos de tópicos de mapa precisam ter 63 caracteres ou menos e um shortTitle com menos de 30 caracteres.
  • Exemplos

Introduções de tópicos de mapa

Todos os tópicos de mapa têm introduções. As introduções devem consistir em uma frase longa e geral ou de alto nível o suficiente para serem escaladas com as alterações futuras do produto. Se você adicionar ou remover artigos em um tópico de mapa, verifique se são necessárias atualizações na introdução.

Artigo

Um artigo é a unidade básica de conteúdo do GitHub Docs. Embora usemos vários tipos de conteúdo, todos eles são publicados como artigos. Cada tipo de conteúdo tem uma finalidade, uma estrutura e um formato próprios, mas usamos elementos padrão em cada tipo de artigo, como introduções, para garantir que os artigos forneçam uma experiência de usuário consistente.

Ordem de conteúdo

Organizamos o conteúdo de maneira previsível em categorias, tópicos de mapa e artigos. Da aplicabilidade mais ampla às informações mais específicas, restritas ou avançadas, seguindo esta ordem:

  • Conteúdo conceitual
  • Conteúdo referencial
  • Conteúdo de procedimentos para habilitar um recurso ou uma configuração
  • Conteúdo de procedimentos sobre como usar um recurso
  • Conteúdo de procedimentos sobre como gerenciar um recurso ou uma configuração
  • Conteúdo de procedimentos sobre como desabilitar um recurso ou uma configuração
  • Conteúdo de procedimentos sobre ações destrutivas (por exemplo, exclusão)
  • Informações sobre solução de problemas

Como reutilizar o conteúdo

Usamos cadeias de caracteres de reutilizáveis e variáveis para usar a mesma parte do conteúdo, como uma etapa de procedimentos ou um parágrafo conceitual, em vários locais. Em geral, não reutilizamos grandes seções de artigos sem um motivo específico. Quando uma seção inteira de um artigo puder ser relevante em mais de um artigo, dê uma olhada na finalidade de ambos. Há uma oportunidade de criar um só artigo de formato longo? Veja os modelos de conteúdo para esclarecer a melhor página permanente para as informações e vincule-a no outro artigo.