Notre modèle de contenu explique l’objectif de chaque type de contenu que nous créons, GitHub Docset ce à inclure lorsque vous écrivez ou mettez à jour un article. Nous utilisons un modèle de contenu pour garantir que notre contenu communique de manière cohérente, claire et complète les informations dont les utilisateurs ont besoin pour atteindre leurs objectifs 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 aide les utilisateurs à se faire une représentation mentale de la documentation et à comprendre comment trouver les informations dont ils ont besoin lorsqu’ils reviennent à GitHub Docs au fil du temps. Il est également plus efficace de maintenir et de mettre à jour un contenu cohérent, ce qui rend la contribution à la documentation plus facile et plus rapide, que vous soyez un contributeur open source effectuant votre premier commit ou un membre de l’équipe GitHub chargé de documenter un tout nouveau produit.
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
- Sujets de la carte
- Articles
- Articles
- Sujets de la carte
- 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 GitHub Docs page d’accueil, docs.github.com, met en évidence les sujets les plus importants que les gens veulent trouver. 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 GitHub des concepts et des pratiques. Par exemple, le groupe « CI/CD et DevOps » inclut des ensembles de documents de niveau supérieur pour GitHub Actions, GitHub Packageset 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 GitHub produit sur lequel ils veulent en savoir plus. 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 l’utilisation d’un produit ou d’une GitHub fonctionnalité, elle peut être ajoutée à la page d’accueil.
Ensemble de documents de niveau supérieur
Les ensembles de documents de niveau supérieur sont organisés autour d’un produit, d’une fonctionnalité ou d’un GitHub flux de travail principal. Tous les ensembles de documents de niveau supérieur apparaissent sur la page d’accueil 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 d’une importance approximativement égale à l’un de l’autre (chacun est centré sur un produit ou une GitHub 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écrit quelle partie de GitHub une personne utilise.
- Exemples
Catégorie
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.
- Suffisamment général ou à haut niveau pour s'adapter aux 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. Les introductions doivent se limiter à une phrase et être suffisamment générales ou de haut niveau pour s'adapter aux futures évolutions 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.
Sujet de la carte
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 sujets de cartes contiennent au moins deux articles. Si des sujets de carte contiennent plus de huit articles, il peut être utile de diviser le contenu en sujets de carte plus spécifiques.
En général, évitez d'avoir un sujet de carte dans une autre carte, sauf s’il s’agit du meilleur moyen de répondre à un besoin spécifique de l’utilisateur.
Titres pour les sujets de carte
- Basés sur une tâche (commencent par un substantif).
- Décrit une tâche plus spécifique dans le flux de travail plus vaste de la catégorie à laquelle elle appartient.
- Sont suffisamment généraux pour prendre en charge les futurs ajouts au produit.
- Les titres de sujet de la carte doivent comporter 63 caractères ou moins et avoir un
shortTitleinférieur à 30 caractères. - Exemples
Introductions pour les thématiques
Tous les sujets de carte ont des introductions. Les introductions doivent se limiter à une phrase et être suffisamment générales ou de haut niveau pour s'adapter aux futures évolutions 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 pour GitHub Docs: alors que nous utilisons plusieurs types de contenu, ils sont tous publiés en tant qu’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)
- Informations sur la 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.