Nous créons des articles référentiels et des sections référentielles au sein d’autres articles.
- Certains sujets majeurs peuvent nécessiter leur propre article référentiel, en particulier si le contenu référentiel est important, comme pour la syntaxe de recherche ou la syntaxe YAML dans GitHub Actions.
- Pour des contenus plus restreints ou des informations plus spécifiques, comme la liste des langues prises en charge ou des exigences matérielles pour une fonctionnalité, utilisez des sections référentielles dans un contexte donné au sein d’articles procéduraux ou conceptuels.
Comment écrire du contenu référentiel
Pour le modèle de contenu référentiel, consultez « Modèles ».
- Écrivez une phrase ou une section conceptuelle entière pour introduire le contenu référentiel.
- Présentez le contenu référentiel réel de manière claire et 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 : Workflow syntax for 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.
Exemples de contenu référentiel
- Articles référentiels
- Raccourcis clavier
- 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 référentielles dans d’autres articles
- « Langues prises en charge » dans GitHub Mobile
- « Considérations matérielles » dans Installation de GitHub Enterprise Server sur AWS