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.
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
shortTitle26 caracteres - Títulos de tópico de mapa: 63 caracteres e
shortTitle29 caracteres - Títulos de artigos: 80 caracteres, 60, se possível, e
shortTitle30 caracteres, de preferência, 20 a 25 caracteres
- Títulos de categoria: 67 caracteres e
- 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.
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
- Artigo com uma só declaração sobre permissões para vários procedimentos: Aplicar as políticas de gerenciamento do repositório na sua empresa
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.
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.
Próximas etapas
Quando um artigo descrever uma etapa em um processo maior ou tiver uma próxima etapa lógica que a maioria das pessoas desejará fazer, inclua uma próxima seção de etapas. Você pode vincular pessoas a artigos ou outros recursos de GitHub.
Exemplos de seções de próximas etapas
## Next steps
- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."
- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."
Neste exemplo de "Primeiros passos vom executores auto-hospedados da sua empresa", a seção próximas etapas inclui links para procedimentos que alguém precisará fazer depois de começar a usar o recurso descrito no artigo.
## Next steps
After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.
Neste exemplo de "Criando uma conta corporativa", a próxima etapa liga ao local onde a maioria das pessoas que acabaram de criar uma conta corporativa gostaria de ir em seguida.
Leitura adicional
Se houver artigos adicionais que ajudem as pessoas a concluir sua tarefa ou aprender a usar o tópico descrito no artigo atual, inclua-os em uma seção de leitura adicional. Inclua apenas links para artigos que ainda não foram vinculados dentro do conteúdo do artigo.
Inclua apenas links que ajudem as pessoas com a tarefa ou tópico em mãos. É melhor estar enfocado e fornecer às pessoas recursos valiosos do que oferecer-lhes todos os elos possíveis.
Formate as seções de leitura adicionais 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