Contenu d'un article GitHub Docs

Chaque article comprend quelques éléments standard et peut inclure des éléments conditionnels ou facultatifs. Le contenu d'un article est également soumis à un ordre standard.

Dans cet article

À propos de la structure d'un article

Dans un article, les sections de contenu sont agencées selon un ordre standard. Chaque article contient des éléments obligatoires. Les articles contiennent également des éléments conditionnels et facultatifs qui sont décrits lors de la conception ou de la création du contenu. Pour plus d'informations, consultez les instructions ci-dessous.

Capture d'écran d'un article avec différentes sections étiquetées : titre, introduction, autorisations, encadré de produits, section conceptuelle, section procédurale et table des matières.

Titres

Les titres décrivent l'objet d'une page et ce qu'une personne apprendra en la lisant.

Les titres peuvent être difficiles à composer. Utilisez ces instructions générales pour vous aider à créer des titres clairs, utiles et descriptifs. Les instructions pour chaque type de contenu de cet article fournissent des règles plus spécifiques concernant les titres.

Titres pour tous les types de contenu

  • Les titres décrivent clairement l'objet d'une page. Ils sont descriptifs et spécifiques.
    • Utilisez : « Exploration des actions dans l'éditeur de workflow »
    • Utilisez : « Exemple de configuration d'un codespace »
    • Évitez : « Utilisation de la barre latérale de l'éditeur de workflow »
    • Évitez : « Exemple »
  • Les titres sont strictement limités en longueur pour qu'ils soient faciles à comprendre (et plus faciles à afficher sur le site) :
    • Titres de catégorie : 67 caractères et shortTitle 26 caractères
    • Titres de thématiques : 63 caractères et shortTitle 29 caractères
    • Titres d'article : 80 caractères, 60 si possible et shortTitle 30 caractères (20 à 25 caractères dans l'idéal)
  • Les titres utilisent la casse des phrases.
    • Utilisez : « Changement d'un message de commit »
    • Évitez : « Changement d'un Message de Commit »
  • Les titres sont cohérents à l'échelle d'un type de contenu. Consultez les instructions spécifiques pour chaque type de contenu.
  • Les titres sont suffisamment généraux pour évoluer avec les modifications apportées au produit, refléter tout le contenu de l'article ou inclure du contenu sur plusieurs produits.
    • Utilisez : « plans de facturation de GitHub »
    • Évitez : « Plans de facturation pour les comptes d'utilisateur et d'organisation »
  • Les titres utilisent une terminologie cohérente.
    • Développez et suivez des modèles au sein d'une catégorie ou sur des sujets similaires.
  • Les titres utilisent la terminologie du produit en question.
  • Écrivez le titre et l'introduction en même temps.
    • Utilisez l'introduction pour développer les idées présentées dans le titre.
    • Pour plus d'informations, consultez les conseils sur les introductions.
  • Si vous avez du mal à trouver un titre, réfléchissez au type de contenu. Vos difficultés à choisir un titre signifient parfois qu'un autre type de contenu serait mieux adapté.
  • Réfléchissez à la façon dont le titre apparaîtra dans les résultats de recherche pour plusieurs produits.
    • Quels mots spécifiques devons-nous inclure dans le titre ou l'introduction afin que les gens ne confondent pas ce contenu avec celui d'un autre produit ?
  • Réfléchissez à quoi ressemblera le titre en production.

Introduction

En haut de chaque page se trouve une introduction qui fournit le contexte et définit les attentes. Elle permet aux lecteurs de décider rapidement si la page leur convient. Les introductions sont également affichées dans les résultats de la recherche pour fournir aux lecteurs des informations contextuelles qui peuvent les aider à choisir un résultat.

Comment écrire une introduction

  • L'introduction d'un article comprend une à deux phrases.
  • L'introduction d'une thématique et d'une catégorie ne comprend qu'une seule phrase.
  • L'introduction d'une référence d'API ne comprend qu'une seule phrase.
    • L'introduction d'une page d'API doit définir la fonctionnalité de manière à ce que le lecteur puisse déterminer si elle répond à ses besoins sans lire la totalité de l'article.
  • Une introduction contient un résumé du contenu de la page et décrit plus en détail l'idée présentée dans le titre.
    • Reprenez le titre de la page en utilisant des synonymes simples pour aider les lecteurs à comprendre différemment l'objectif de l'article. Dans la mesure du possible, évitez de répéter les mots utilisés dans le titre.
  • Les introductions étant relativement générales, vous pouvez le plus souvent les conserver telles quelles, même si le contenu de la page est modifié par la suite.
  • Pour faciliter les recherches, incluez des mots clés dans le sujet de la page dans l'introduction.
  • Quand un terme de l'introduction a un acronyme utilisé plus loin dans l'article, indiquez cet acronyme.
  • Les introductions ne contiennent généralement aucune autorisation pour les tâches contenues dans l'article.

Instructions d'autorisations

Chaque procédure comprend une déclaration d'autorisations qui explique le rôle requis pour effectuer l'action décrite dans la procédure. Cela permet aux utilisateurs de savoir s'ils seront en mesure d'effectuer une tâche.

Il est parfois utile de mentionner les autorisations requises dans le contenu conceptuel, en particulier dans les articles conceptuels autonomes. Veillez également à inclure une déclaration d'autorisations dans les procédures associées (ou écrivez un article plus long combinant les différents contenus).

Comment écrire une déclaration d'autorisations

  • Si un seul ensemble d'autorisations s'applique à toutes les procédures d'un article, utilisez le frontmatter permissions.
  • Lorsqu'un article contient plusieurs procédures et que différentes autorisations s'appliquent, incluez une déclaration d'autorisations distincte sous chaque en-tête approprié avant chaque procédure.
  • N'incluez pas d'autorisations dans l'introduction d'un article.
  • Les rôles existent à différents niveaux. Faites uniquement référence au rôle au même niveau que l'action. Par exemple, vous avez besoin d'un accès administrateur à un dépôt (rôle au niveau du dépôt) pour configurer des branches protégées. Vous pouvez obtenir un accès administrateur à un dépôt si vous êtes propriétaire d'organisation (rôle au niveau de l'organisation), mais le rôle au niveau du dépôt est ce qui régit réellement votre capacité à effectuer l'action. Il s'agit donc du seul rôle qui doit être mentionné dans la déclaration d'autorisations.
  • Texte à utiliser dans une déclaration d'autorisations :
    • [RÔLE DE COMPTE] peut [ACTION].
    • Les personnes disposant d'un accès [RÔLE DE FONCTIONNALITÉ] pour une [FONCTIONNALITÉ] peuvent [ACTION].
    • ÉVITEZ : [RÔLE DE COMPTE] et les personnes disposant d'un accès [RÔLE DE FONCTIONNALITÉ] pour une [FONCTIONNALITÉ] peuvent [ACTION].

Exemples de déclarations d'autorisations

Encadré de produits

Utilisez un encadré de produits quand une fonctionnalité est disponible uniquement dans des produits spécifiques et que cette disponibilité ne peut pas être communiquée uniquement par le versioning. Par exemple, si une caractéristique est disponible pour GHEC et GHES, vous ne pouvez proposer du contenu sur cette caractéristique que pour GHEC et GHES. Si une caractéristique est disponible pour Pro, Team, GHEC et GHES (mais pas pour Free), utilisez une notification de produit pour indiquer cette disponibilité.

Tous les encadrés de produits sont stockés en tant qu'éléments réutilisables dans gated-features et ajoutés au frontmatter YAML pour les articles pertinents.

Comment écrire un encadré de produits

  • Les encadrés de produits suivent un format strict pour identifier clairement la fonctionnalité en question et les produits dans lesquels elle est disponible.
  • Les encadrés de produits incluent également un lien vers « Produits de GitHub » et, à l'occasion, un lien vers un autre article pertinent.
  • Exemples :
    • [Nom de la fonctionnalité] est disponible dans [produit(s)]. Pour plus d'informations, consultez « Produits de GitHub ».
    • [Nom de la fonctionnalité] est disponible dans les dépôts publics avec [produit(s) gratuit(s)], et dans les dépôts publics et privés avec [produits payants]. Pour plus d'informations, consultez « Produits de GitHub ».

Exemples d'articles avec des encadrés de produits

Consultez les fichiers sources et gated-features pour voir comment le contenu source est écrit.

Sélecteur d'outils

Le contenu de certains articles varie en fonction de l'outil exécuté par l'utilisateur pour effectuer une tâche, par exemple GitHub CLI ou GitHub Desktop. Pour la plupart des contenus, les mêmes informations conceptuelles ou procédurales conviennent à plusieurs outils. Toutefois, si la seule façon de présenter les informations de manière claire et précise consiste à différencier le contenu par outil, utilisez le sélecteur d'outils. N'utilisez pas le sélecteur d'outils pour simplement afficher des exemples dans différents langages. Utilisez uniquement le sélecteur d'outils si les tâches ou les concepts changent en fonction de l'outil exécuté par l'utilisateur. Pour plus d’informations, consultez « Création de sélecteurs d’outils dans les articles ».

Table des matières

Les tables des matières sont générées automatiquement. Pour plus d’informations, consultez Mini-tables des matières générées automatiquement.

Contenu conceptuel

Le contenu conceptuel aide les utilisateurs à comprendre un sujet ou à en savoir plus. Pour plus d'informations, consultez Type de contenu conceptuel dans le modèle de contenu.

Contenu référentiel

Le contenu référentiel fournit des informations structurées concernant l'utilisation active d'un produit ou d'une fonctionnalité. Pour plus d'informations, consultez Type de contenu référentiel dans le modèle de contenu.

Prérequis

Les prérequis sont des informations que les utilisateurs doivent connaître avant d'entamer une procédure. Ils indiquent les préparations à effectuer avant de démarrer une tâche.

Comment écrire des prérequis

  • Écrivez les prérequis juste avant les étapes numérotées d'une procédure.
  • Vous pouvez utiliser une liste, une phrase ou un paragraphe pour expliquer les prérequis.
  • Vous pouvez également utiliser une section de prérequis distincte dans les cas suivants :
    • Les informations requises sont très importantes et incontournables.
    • Il y a plusieurs prérequis.
  • Pour répéter ou souligner des informations importantes sur la perte de données ou les actions destructrices, vous pouvez également utiliser un encadré « Avertissement  ou « Danger » pour partager un prérequis.

Instructions relatives aux titres pour les prérequis

  • Si vous utilisez une section distincte, utilisez un en-tête appelé Prerequisites

Exemples d'articles avec des sections de prérequis

Contenu procédural

Le contenu procédural aide les utilisateurs à effectuer des tâches. Pour plus d'informations, consultez Type de contenu procédural dans le modèle de contenu.

Contenu de dépannage

Le contenu de dépannage aide les utilisateurs à éviter les erreurs ou à les résoudre. Pour plus d'informations, consultez Type de contenu de dépannage dans le modèle de contenu.

Étapes suivantes

Lorsqu’un article décrit une étape dans un processus plus large ou comprend une étape logique suivante que la plupart des personnes souhaiteront effectuer, incluez une section Étapes suivantes. Vous pouvez lier des personnes à des articles ou d’autres ressources GitHub.

Exemples de sections Étapes suivantes

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

Dans cet exemple de Bien démarrer avec les exécuteurs auto-hébergés pour votre entreprise, la section Étapes suivantes inclut des liens vers des procédures que quelqu’un devra effectuer après avoir commencé à utiliser la fonctionnalité décrite dans l’article.

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

Dans cet exemple de Création d’un compte d’entreprise, l’étape suivante propose des liens vers l’emplacement où la plupart des personnes qui viennent de terminer la création d’un compte d’entreprise souhaiteront passer ensuite.

Pour aller plus loin

S’il existe des articles supplémentaires qui aident les personnes à effectuer leur tâche ou à apprendre à utiliser la rubrique décrite dans l’article actuel, incluez-les dans une section Pour aller plus loin. Incluez uniquement des liens vers des articles qui n’ont pas déjà été liés dans le contenu de l’article.

Incluez uniquement des liens qui aident les personnes pour la tâche ou rubrique dont il est question. Il est préférable de vous concentrer sur les ressources précieuses que vous pouvez offrir aux personnes plutôt que d’inclure tous les liens possibles.

Mettez en forme d’autres sections « Pour aller plus loin » à l’aide de listes non triées. Consultez Guide de style pour savoir comment écrire des liens.

Titre et mise en forme d'une section « Pour aller plus loin »

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name