Notre modèle de contenu explique l’objectif de chaque type de contenu que nous créons dans GitHub Docs et ce que vous devez inclure quand vous écrivez ou mettez à jour un article. Nous utilisons un modèle pour garantir que notre contenu communique de manière cohérente, claire et exhaustive les informations dont ont besoin les utilisateurs pour atteindre leurs objectifs avec GitHub.
Nous utilisons ces types de contenu dans tous les ensembles de documentation pour fournir une expérience utilisateur cohérente, où tout type de contenu s’applique à n’importe quel produit ou n’importe quelle audience. Nos types de contenu évoluent au fil du temps et nous ajoutons de nouveaux types en fonction des besoins. Nous publions uniquement le contenu qui est conforme au modèle.
La cohérence permet aux utilisateurs de former mentalement des modèles de la documentation et de comprendre comment trouver les informations dont ils ont besoin quand ils reviennent à GitHub Docs par la suite. Il est également plus efficace de gérer et de mettre à jour du contenu cohérent. Que vous soyez contributeur open source effectuant votre premier commit ou rédacteur au sein de l’équipe GitHub documentant un tout nouveau produit, vous pouvez facilement et rapidement contribuer aux documents.
Structure du contenu
Les documents sont organisés en plusieurs niveaux de hiérarchie sur notre site.
- Ensemble de documents de niveau supérieur
- Catégories
- Thématiques
- Articles
- Articles
- Thématiques
- Articles
- Catégories
L’organisation du contenu doit être équilibrée entre la création de regroupements spécifiques qui aident les personnes à trouver ce qu’elles recherchent et la limitation des couches de hiérarchie à travers lesquelles les personnes doivent naviguer. Les hiérarchies profondes avec de nombreuses thématiques imbriquées peuvent compliquer la recherche d’articles spécifiques. Les hiérarchies larges avec de nombreuses catégories ou articles au même niveau compliquent l’évaluation et le choix de sélection pour les personnes.
Contenu de la page d’accueil
La page d’accueil de GitHub Docs, docs.github.com, présente les sujets les plus importants pour les utilisateurs. Nous limitons le nombre d’ensembles de documents dans la page d’accueil pour que les personnes puissent trouver les informations qui les intéressent et pour ne pas surcharger la page d’accueil au point de rendre les recherches difficiles.
La page d’accueil inclut tous les ensembles de documents de niveau supérieur et certaines catégories. Le contenu de la page d’accueil est organisé autour des concepts et des pratiques de GitHub. Par exemple, le groupe « CI/CD et DevOps » inclut des ensembles de documents de niveau supérieur pour GitHub Actions, GitHub Packages et GitHub Pages.
Ajout d’un ensemble de documents à la page d’accueil
L’objectif de la page d’accueil est d’aider les utilisateurs à trouver des informations sur la fonctionnalité ou le produit GitHub qu’ils souhaitent approfondir. Chaque élément ajouté à la page d’accueil affaiblissant la découvrabilité des autres éléments, nous limitons le nombre d’ensembles de documents qui figurent dans la page d’accueil.
Si un nouvel ensemble de documents de niveau supérieur est créé, il est ajouté à la page d’accueil.
Si une catégorie sert de point de départ pour utiliser un produit ou une fonctionnalité GitHub, elle peut être ajoutée à la page d’accueil.
Par exemple, sous le regroupement « Sécurité » dans la page d’accueil, en plus de l’ensemble de documents de niveau supérieur Sécurité du code, les catégories Sécurité de la chaîne logistique, Avis de sécurité, Dependabot, Code scanning et Secret scanning sont incluses, car chacune de ces catégories est le point d’entrée des produits et fonctionnalités GitHub. La Vue d’ensemble de la sécurité ne figure pas dans la page d’accueil, car elle fournit des informations supplémentaires sur l’utilisation des produits de sécurité du code et ne constitue pas une introduction à un produit ou à une fonctionnalité.
Ensemble de documents de niveau supérieur
Les ensembles de documents de niveau supérieur s’articulent autour d’un produit, d’une fonctionnalité ou d’un workflow de base GitHub. Tous les ensembles de documents de niveau supérieur sont présents dans la page d’accueil de GitHub Docs. Il est uniquement nécessaire de créer un ensemble de documents de niveau supérieur quand le nouvel ensemble renferme une grande quantité de contenu, quand plusieurs catégories sont réparties en thématiques et quand la rubrique s’applique à tous les produits, fonctionnalités ou types de comptes. Si le contenu peut tenir dans un ensemble de documents de niveau supérieur existant, il est probablement judicieux de l’ajouter à cet ensemble.
- Les ensembles de documents de niveau supérieur sont à peu près d’importance égale (chaque ensemble est centré sur un produit GitHub ou une fonctionnalité majeure).
- La plupart des ensembles de documents de niveau supérieur ont une page d’accueil, sauf exception notable. Par exemple, l’ensemble de documents Politique du site ne comprend pas de guides ou d’articles procéduraux comme les autres ensembles. Il n’a donc pas de page d’accueil.
- Les ensembles de documents de niveau supérieur peuvent contenir un mélange de catégories, de thématiques ou d’articles.
Titres pour les ensembles de documents de niveau supérieur
- Basés sur une fonctionnalité ou un produit.
- Décrivent la partie de GitHub qu’une personne utilise.
- Exemples
Category
Les catégories s’articulent autour d’une fonctionnalité ou d’un ensemble discret de tâches au sein d’un ensemble de documents de niveau supérieur aligné sur les thèmes d’un produit. Le sujet d’une catégorie est assez restreint, ce qui vous permet de gérer facilement son contenu sans que celui-ci devienne trop volumineux. Certaines catégories apparaissent dans la page d’accueil.
- Les catégories sont souvent petites au départ, mais elles évoluent avec le produit.
- Les catégories peuvent contenir des thématiques pour subdiviser le contenu autour de tâches ou de parcours utilisateur plus spécifiques.
- Utilisez de longs articles procéduraux pour regrouper des blocs de contenu connexes et simplifier les articles au sein de la catégorie.
- Quand des catégories comportent plus de dix articles, envisagez de diviser le contenu en thématiques ou en catégories supplémentaires.
- Les catégories peuvent contenir un mélange de thématiques ou d’articles.
Titres pour les catégories
- Basés sur une tâche (commencent par un substantif).
- Décrivent l’objectif général de la fonctionnalité ou du produit.
- Sont suffisamment généraux pour prendre en charge les futures améliorations du produit.
- Les titres de catégories doivent comporter 67 caractères ou moins et avoir un
shortTitlede moins de 27 caractères. - Exemples
Introductions pour les catégories
Toute catégorie doit avoir une introduction. Une introduction se limite à une phrase et doit être suffisamment générale pour prendre en charge les futures améliorations du produit. Si vous modifiez considérablement la structure d’une catégorie, vérifiez son introduction pour déterminer si une mise à jour est nécessaire.
Thématique
Les thématiques présentent une section d’une catégorie. Elles regroupent les articles d’une catégorie autour de workflows ou de sujets plus spécifiques qui s’inscrivent dans la tâche de plus grande envergure de la catégorie.
Les thématiques contiennent au moins deux articles. Si une thématique contient plus de huit articles, il peut être utile de diviser le contenu en thématiques plus spécifiques.
En général, évitez de créer une thématique au sein d’une thématique, sauf s’il s’agit du meilleur moyen de répondre à un besoin spécifique de l’utilisateur.
Titres pour les thématiques
- Basés sur une tâche (commencent par un substantif).
- Décrivent une tâche plus spécifique dans le workflow de plus grande envergure de la catégorie parente.
- Sont suffisamment généraux pour prendre en charge les futurs ajouts au produit.
- Les titres de thématiques doivent comporter 63 caractères ou moins et avoir un
shortTitlede moins de 30 caractères. - Exemples
Introductions pour les thématiques
Toute thématique doit avoir une introduction. Une introduction se limite à une phrase et doit être suffisamment générale pour prendre en charge les futures améliorations du produit. Si vous ajoutez ou supprimez des articles dans une thématique, vérifiez son introduction pour déterminer si une mise à jour est nécessaire.
Article
Un article est l’unité de base du contenu de GitHub Docs. Bien que nous utilisions plusieurs types de contenu, ils sont tous publiés sous la forme d’articles. Chaque type de contenu a un objectif, un format et une structure qui lui sont propres, mais nous utilisons des éléments standard dans chaque type d’article, comme les introductions, afin de garantir une expérience utilisateur cohérente.
Ordre du contenu
Nous organisons le contenu de manière prévisible dans des catégories, des thématiques et des articles. Des informations les plus générales à celles plus spécifiques, étroites ou avancées, l’ordre du contenu est le suivant :
- Contenu conceptuel
- Contenu référentiel
- Contenu procédural pour activer une fonctionnalité ou un paramètre
- Contenu procédural sur l’utilisation d’une fonctionnalité
- Contenu procédural sur la gestion d’une fonctionnalité ou d’un paramètre
- Contenu procédural sur la désactivation d’une fonctionnalité ou d’un paramètre
- Contenu procédural sur des actions destructives (par exemple, suppression)
- Résolution de problèmes
Réutilisation du contenu
Nous utilisons des chaînes réutilisables et variables pour pouvoir utiliser le même bloc de contenu, comme une étape procédurale ou un paragraphe conceptuel, à différents endroits. En règle générale, nous ne réutilisons pas de grandes sections d’articles, sauf raison spécifique. Quand une section entière d’un article peut convenir à plusieurs articles, examinez l’objectif de chacun de ces articles. Est-il possible de créer un seul article au format long ? Reportez-vous aux modèles de contenu pour déterminer le meilleur emplacement permanent pour les informations, puis créez un lien vers celles-ci dans l’autre article.