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.

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.

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

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 « AUTOTITRE » 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 « AUTOTITRE » 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 « AUTOTITRE » 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 « AUTOTITRE » dans le modèle de contenu.

Pour aller plus loin

Les sections « Pour aller plus loin » listent d’autres articles ciblés qui ne figurent pas dans le contenu de l’article. Utilisez ces sections si vous estimez qu'elles apportent une valeur ajoutée. Faites preuve de modération. 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