Conteúdo de um artigo do GitHub Docs

Cada artigo inclui alguns elementos padrão e pode incluir elementos condicionais ou opcionais. Também usamos uma ordem padrão para o conteúdo de um artigo.

Neste artigo

Sobre a estrutura de um artigo

Em um artigo, há uma ordem padrão de seções de conteúdo. Cada artigo contém elementos obrigatórios. Os artigos também conterão elementos condicionais e elementos opcionais descritos no design ou na criação de conteúdo. Leia as diretrizes abaixo para obter mais detalhes.

Captura de tela de um artigo com título, introdução, permissões, texto explicativo do produto, seção conceitual, seção de procedimentos e sumário rotulado.

Títulos

Os títulos descrevem por completo do que trata uma página e o que alguém aprenderá com a leitura dela.

Os títulos podem ser difíceis. Use essas diretrizes gerais para ajudar a criar títulos claros, úteis e descritivos. As diretrizes de cada tipo de conteúdo neste artigo fornecem regras de título mais específicas.

Títulos para todos os tipos de conteúdo

  • Os títulos descrevem claramente do que trata uma página. Eles são descritivos e específicos.
    • Use: “Navegar em ações no editor do fluxo de trabalho”
    • Use: “Exemplo de configuração de um codespace”
    • Evite: “Usar a barra lateral do editor de fluxo de trabalho”
    • Evite: “Exemplo”
  • Os títulos têm limites rígidos quanto ao tamanho para mantê-los fáceis de entender (e mais fáceis de renderizar no site):
    • Títulos de categoria: 67 caracteres e shortTitle 26 caracteres
    • Títulos de tópico de mapa: 63 caracteres e shortTitle 29 caracteres
    • Títulos de artigos: 80 caracteres, 60, se possível, e shortTitle 30 caracteres, de preferência, 20 a 25 caracteres
  • Os títulos usam letra maiúscula inicial.
    • Use: “Alterar uma mensagem de compromisso”
    • Evite: “Alterar uma mensagem de compromisso”
  • Os títulos são consistentes em um tipo de conteúdo. Confira as diretrizes específicas para cada tipo de conteúdo.
  • Os títulos são gerais o suficiente para serem escalados com as alterações do produto, refletir todo o conteúdo do artigo ou incluir o conteúdo em vários produtos.
    • Use: “Planos de faturamento do GitHub”
    • Evite: "Planos de cobrança para contas de usuário e de organização"
  • Os títulos usam uma terminologia consistente.
    • Desenvolva e siga padrões em uma categoria ou em assuntos semelhantes.
  • Os títulos usam a terminologia do próprio produto.
  • Escreva o título e a introdução ao mesmo tempo.
    • Use a introdução para desenvolver as ideias apresentadas no título.
    • Confira as diretrizes sobre introduções para obter mais informações.
  • Se for difícil criar um título, considere o tipo de conteúdo. Às vezes, as dificuldades na escolha de um título indicam que outro tipo de conteúdo se encaixará melhor.
  • Pense em como o título aparecerá nos resultados da pesquisa para vários produtos.
    • Quais palavras específicas precisamos incluir no título ou na introdução para que as pessoas não o confundam com um conteúdo sobre outro produto?
  • Pense em como o título ficará na produção.

Texto explicativo do produto

Use o texto explicativo do produto quando um recurso estiver disponível apenas em produtos específicos e essa disponibilidade não puder ser transmitida apenas pelo controle de versão. Por exemplo, se um recurso só estiver disponível no GHEC e no GHES, você poderá ver o conteúdo sobre o recurso somente para o GHEC e o GHES. Se um recurso estiver disponível no Pro, no Team, no GHEC e no GHES (mas não no Gratuito), use um texto explicativo do produto para informar sobre essa disponibilidade.

Todos os textos explicativos do produto são armazenados como reutilizáveis em gated-features e adicionados na matéria frontal YAML dos artigos relevantes.

Como escrever um texto explicativo do produto

  • Os textos explicativos do produto seguem um formato estrito, identificando claramente o recurso e os produtos em que ele está disponível.
  • Os textos explicativos do produto também incluem um link para “produtos do GitHub” e, ocasionalmente, para outro artigo relevante.
  • Exemplos:
    • O [nome do recurso] está disponível em [produtos]. Para obter mais informações, confira “Produtos do GitHub”.
    • O [nome do recurso] está disponível em repositórios públicos com os [produtos gratuitos] e em repositórios públicos e privados com os [produtos pagos]. Para obter mais informações, confira “Produtos do GitHub”.

Exemplos de artigos com textos explicativos do produto

Verifique os arquivos de origem e os gated-features veja como o conteúdo de origem foi escrito.

Introdução

A parte superior de cada página traz uma introdução que fornece o contexto e define as expectativas, permitindo que os leitores decidam rapidamente se a página é relevante para eles. As introduções também são exibidas nos resultados da pesquisa para fornecer informações contextuais a fim de ajudar os leitores a escolher um resultado.

Como escrever uma introdução

  • As introduções de artigos têm de uma a duas frases.
  • As introduções de tópicos de mapa e de categorias têm uma frase.
  • As introduções de referência de API têm uma frase.
    • A introdução de uma página de API deve definir o recurso para que alguém saiba se o recurso atende às necessidades sem ler o artigo inteiro.
  • As introduções contêm um resumo de alto nível do conteúdo da página, desenvolvendo a ideia apresentada em um título com mais detalhes.
    • Use sinônimos de palavras acessíveis no título da página para ajudar os leitores a entender a finalidade do artigo de maneira diferente. Evite repetir palavras do título quando possível.
  • As introduções são relativamente permanentes e de alto nível, portanto, podem ser escaladas com as alterações futuras com o conteúdo da página sem a necessidade de serem atualizadas com frequência.
  • Para aprimorar a pesquisa, inclua palavras-chave no assunto da página na introdução.
  • Quando um termo da introdução tiver um acrônimo que usaremos em outro lugar no artigo, indique o acrônimo.
  • As introduções costumam não conter permissões para as tarefas contidas no artigo.

Instruções de permissões

Cada procedimento inclui uma declaração sobre permissões que explica a função necessária para executar a ação descrita no procedimento, o que ajuda as pessoas a entender se elas conseguirão realizar a tarefa.

Ocasionalmente, é relevante mencionar as permissões necessárias no conteúdo conceitual, especialmente em artigos conceituais autônomos. Inclua também uma declaração sobre permissões em procedimentos relacionados (ou escreva um artigo mais longo combinando todo o conteúdo).

Como escrever uma declaração sobre permissões

  • Quando um só conjunto de permissões se aplica a todos os procedimentos em um artigo, use a matéria frontal de permissões.
  • Quando um artigo contém vários procedimentos e permissões diferentes se aplicam, inclua uma instrução de permissões separada em cada cabeçalho relevante, antes de cada procedimento.
  • Não inclua permissões na introdução de um artigo.
  • As funções existem em níveis diferentes. Refira-se apenas à função no mesmo nível da ação. Por exemplo, você precisa ter acesso de administrador em um repositório (função no nível do repositório) para configurar os branches protegidos. Você pode obter acesso de administrador em um repositório sendo um proprietário da organização (função no nível da organização), mas a função no nível do repositório é o que realmente controla sua capacidade de executar a ação, de modo que é a única função que deve ser mencionada na declaração sobre permissões.
  • Linguagem a ser usada em uma declaração sobre permissões:
    • A [FUNÇÃO DE CONTA] pode [AÇÃO].
    • As pessoas com acesso de [FUNÇÃO DE RECURSO] em um [RECURSO] podem [AÇÃO].
    • EVITE: A [FUNÇÃO DE CONTA] e as pessoas com acesso de [FUNÇÃO DE RECURSO] em um [RECURSO] podem [AÇÃO].

Exemplos de declarações sobre permissões

Alternador de ferramentas

Alguns artigos trazem um conteúdo que varia conforme a ferramenta que alguém usa para realizar uma tarefa, como a GitHub CLI ou o GitHub Desktop. Para a maior parte do conteúdo, as mesmas informações conceituais ou de procedimentos serão precisas para várias ferramentas. No entanto, se a única maneira de deixar as informações claras e precisas for distinguindo o conteúdo por ferramenta, use o alternador de ferramentas. Não use o alternador de ferramentas apenas para mostrar exemplos em linguagens diferentes. Só use o alternador de ferramentas se as tarefas ou os conceitos mudarem de acordo com a ferramenta usada. Para obter mais informações, confira "Como criar alternadores de ferramentas em artigos".

Sumário

Os sumários são gerados automaticamente. Para obter mais informações, confira "Minissumários gerados automaticamente".

Conteúdo conceitual

O conteúdo conceitual ajuda as pessoas a entender um tópico ou aprender mais sobre ele. Para obter mais informações, consulte "Tipo de conteúdo conceitual" no modelo de conteúdo.

Conteúdo referencial

O conteúdo referencial fornece informações estruturadas relacionadas ao uso ativo de um produto ou de um recurso. Para obter mais informações, consulte "Tipo de conteúdo referencial" no modelo de conteúdo.

Pré-requisitos

Os pré-requisitos são informações que as pessoas precisam saber antes de prosseguir com um procedimento, de modo que possam preparar tudo do que precisam antes de iniciar a tarefa.

Como escrever pré-requisitos

  • Escreva os pré-requisitos imediatamente antes das etapas numeradas de um procedimento.
  • Você pode usar uma lista, uma frase ou um parágrafo para explicar os pré-requisitos.
  • Você também poderá usar uma seção de pré-requisitos separada quando:
    • As informações de pré-requisito forem muito importantes e não possam ser perdidas.
    • Houver mais de um pré-requisito.
  • Para repetir ou realçar informações importantes sobre perda de dados ou ações destrutivas, use também um texto explicativo de aviso ou perigo para compartilhar um pré-requisito.

Diretrizes de título para pré-requisitos

  • Ao usar uma seção separada, use um cabeçalho chamado Prerequisites

Exemplos de artigos com seções de pré-requisitos

Conteúdo de procedimentos

O conteúdo de procedimentos ajuda as pessoas a realizar tarefas. Para obter mais informações, consulte "Tipo de conteúdo de procedimento" no modelo de conteúdo.

Conteúdo de solução de problemas

O conteúdo de solução de problemas ajuda as pessoas a evitar ou resolver erros. Para obter mais informações, consulte "Tipo de conteúdo de solução de problemas" no modelo de conteúdo.

Leitura adicional

As seções de leitura adicional realçam os artigos direcionados adicionais que ainda não foram incluídos no conteúdo ou na barra lateral do artigo. Use as seções de leitura adicional com moderação quando elas fornecerem valor real. 's Formatar seções de leitura adicional usando listas não ordenadas. Consulte "Guia de estilo" para ver instruções sobre como gravar links.

Título e formato para as seções de leitura adicional

### Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name