O conteúdo de referência é consultado para obter informações específicas. São informações que você pode verificar rapidamente, o que significa que há menos ênfase em frases e parágrafos.
A referência inclui informações que podem ser melhor representadas em tabelas, listas ou outros formatos estruturados. Podemos pensar em referência como incluindo nosso conteúdo de pipeline gerado automaticamente e outros conteúdos que poderiam ser potencialmente automatizados.
O conteúdo de referência aparece em artigos de referência e seções de referência em outros artigos.
- Alguns assuntos principais podem exigir seu próprio artigo de referência, especialmente se houver uma grande quantidade de conteúdo de referência, como sintaxe de pesquisa ou sintaxe YAML em GitHub Actions.
- Para quantidades menores de conteúdo ou informações mais específicas, como uma lista de linguagens com suporte de um recurso ou requisitos de hardware, use seções de referência no contexto em artigos conceituais ou processuais.
Como escrever conteúdo de referência
Para o modelo de conteúdo de referência, consulte Modelos.
- Escreva uma frase ou uma seção conceitual inteira para introduzir o conteúdo de referência.
- Apresentar o conteúdo de referência real de forma 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 subdivisõ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.
- Títulos curtos devem ser uma palavra ou uma frase substantiva curta. Exemplo: "Modelos de IA".
Exemplos de conteúdo de referência
- Artigos de referência * Eventos de registro de auditoria para a sua organização * Habilidades de funções em uma empresa * Pontos de extremidade da API REST para faturamento na documentação da API REST * Mutações na documentação da API do GraphQL
- Seções de referência em outros artigos
- "Linguagens compatíveis" em GitHub Mobile
- "Considerações sobre hardware" em Instalando o GitHub Enterprise Server no AWS