Criamos artigos referenciais e seções referenciais dentro de outros artigos.
- Alguns assuntos principais podem exigir um artigo referencial próprio, especialmente se houver um grande volume de conteúdo referencial, como sintaxe de pesquisa ou sintaxe YAML do GitHub Actions.
- Para volumes menores de conteúdo ou informações mais específicas, como uma lista dos requisitos de hardware ou de linguagens compatíveis de um recurso, use seções referenciais no contexto em artigos conceituais ou de procedimentos.
Como escrever um conteúdo referencial
Para ver o modelo de conteúdo referencial, confira Modelos.
- Escreva uma frase ou uma seção conceitual inteira para introduzir o conteúdo referencial.
- Apresente o conteúdo referencial real de maneira clara e consistente.
- Para assuntos com um só elemento a ser explicado, use uma lista.
- Para assuntos com vários elementos a serem explicados, use uma tabela.
- Para um conteúdo referencial mais longo, como a sintaxe YAML para fluxos de trabalho, use cabeçalhos de maneira consistente.
- Cabeçalhos H2 para cada seção distinta.
- Cabeçalhos H3 para subseções, como exemplos.
- Exemplo: Sintaxe de fluxo de trabalho para o GitHub Actions
Títulos para conteúdo referencial
- Os artigos referenciais ou os cabeçalhos de seções referenciais descrevem claramente o conteúdo da seção e costumam começar com substantivos.
- Os títulos incluem informações suficientes para serem acessíveis aos usuários iniciantes e descrevem por completo o conteúdo de cada seção.
- Nos títulos, o uso de substantivos sequenciais é evitado. Use preposições para separar sequências longas de substantivos.
Exemplos de conteúdo referencial
- Artigos referenciais
- Atalhos do teclado
- Funções em uma empresa
- Pontos de extremidade da API REST para cobrança na documentação da API REST
- Mutações na documentação da API do GraphQL
- Seções referenciais em outros artigos
- "Linguagens compatíveis" em GitHub Mobile
- "Considerações sobre hardware" em Instalar o GitHub Enterprise Server no AWS