Le contenu de référence est consulté pour obtenir des informations spécifiques. Il s’agit d’informations que vous pouvez vérifier rapidement, ce qui signifie qu’il y a moins d’accent sur les phrases et les paragraphes.
Les informations de référence incluent des informations qui peuvent être mieux représentées dans des tables, des listes ou d’autres formats structurés. Nous pourrions considérer la référence comme incluant notre contenu de pipeline généré automatiquement et d’autres contenus susceptibles d’être automatisés.
Le contenu de référence apparaît dans les articles de référence et les sections de référence dans d’autres articles.
- Certains sujets majeurs peuvent nécessiter leur propre article de référence, en particulier s’il existe une grande quantité de contenu de référence, comme pour la syntaxe de recherche ou la syntaxe YAML dans GitHub Actions.
- Pour de plus petites quantités de contenu ou des informations plus spécifiques, telles que la liste des langages ou exigences matérielles pris en charge d’une fonctionnalité, utilisez des sections de référence dans le contexte dans des articles procéduraux ou conceptuels.
Comment écrire du contenu de référence
Pour le modèle de contenu de référence, consultez Modèles.
- Écrivez une phrase ou une section conceptuelle entière pour introduire le contenu de référence.
- Présenter le contenu de référence réel clairement et de manière cohérente.
- Pour les sujets comportant un seul élément à expliquer, utilisez une liste.
- Exemple : Rôles de dépôt pour une organisation
- Pour les sujets comportant plusieurs éléments à expliquer, utilisez un tableau.
- Exemple : Rôles de dépôt pour une organisation
- Pour le contenu référentiel plus long, comme la syntaxe YAML pour les workflows, utilisez des en-têtes de manière cohérente.
- En-têtes H2 pour chaque section distincte.
- En-têtes H3 pour les sous-sections, comme des exemples.
- Exemple : Syntaxe de flux de travail pour GitHub Actions
Titres pour les contenus référentiels
- Les articles référentiels ou en-têtes de sections référentielles décrivent clairement le contenu de la section et commencent généralement par un nom.
- Les titres incluent suffisamment d’informations pour être accessibles aux utilisateurs débutants et décrivent entièrement le contenu de chaque section.
- Évitez l’empilement de noms dans les titres et utilisez des prépositions pour décomposer les longues chaînes de noms.
- Les titres courts doivent être un mot ou une phrase abrégée. Exemple : « Modèles IA ».
Exemples de contenu de référence
- Articles de référence * Événements du journal d’audit pour votre organisation * Compétences des rôles dans une entreprise * Points de terminaison d’API REST pour la facturation dans la documentation de l’API REST * Mutations dans la documentation de l’API GraphQL
- Sections de référence dans d’autres articles
- « Langues prises en charge » dans GitHub Mobile
- « Considérations matérielles » dans Installation de GitHub Enterprise Server sur AWS