Meilleures pratiques pour GitHub Docs

Suivez ces meilleures pratiques pour créer une documentation conviviale et facile à comprendre.

Dans cet article

À propos de la documentation de GitHub

Chez GitHub, nous nous efforçons de créer une documentation précise, utile, inclusive, accessible et simple d’utilisation.

Avant de contribuer à GitHub Docs, prenez le temps de vous familiariser avec la philosophie, les principes fondamentaux et les principes de conception du contenu de GitHub :

Meilleures pratiques pour l’écriture de la documentation GitHub

Que vous créiez un article ou mettiez à jour un article existant, vous devez suivre ces recommandations lors de l’écriture pour GitHub Docs :

Aligner le contenu sur les besoins de l’utilisateur

Avant de commencer, il est important de comprendre pour qui vous écrivez, quels sont leurs objectifs, les principales tâches ou concepts que l’article traitera et quel type de contenu écrire.

Définir l’audience

  • Qui lira ce contenu ?
  • Qu'essaient-ils de faire ?

Définir l’objectif principal

  • Qu’est-ce que le lecteur doit pouvoir faire ou comprendre après avoir lu cet article ? Choisissez une ou deux tâches ou concepts que le contenu abordera.
  • S’il existe des tâches, des concepts ou des informations supplémentaires qui ne sont pas essentiels, demandez-vous s’ils peuvent être placés plus bas dans l’article, déplacés vers un autre article ou omis complètement.

Déterminer le type de contenu

Déterminez le type de contenu que vous allez écrire, en fonction de l’audience prévue et de l’objectif principal du contenu. GitHub Docs utilisent les types de contenu suivants :

Par exemple, utilisez le type de contenu conceptuel pour aider les lecteurs à comprendre les principes de base d’une fonctionnalité ou d’un sujet et comment ils peuvent les aider à atteindre leurs objectifs. Utilisez le type de contenu procédural pour aider les lecteurs à effectuer une tâche spécifique du début à la fin.

Structurer le contenu à des fins de lisibilité

Utilisez les meilleures pratiques suivantes pour structurer le contenu. Lorsque vous ajoutez du contenu à un article existant, suivez la structure existante dans la mesure du possible.

  • Fournissez le contexte initial. Définissez le sujet et indiquez sa pertinence pour le lecteur.
  • Structurez le contenu dans un ordre logique, par importance et pertinence. Placez les informations par ordre de priorité, et dans l’ordre dont les utilisateurs en auront besoin.
  • Évitez les phrases longues et les paragraphes.
    • Présentez les concepts un par un.
    • Utilisez une idée par paragraphe.
    • Utilisez une idée par phrase.
  • Mettez l’accent sur les informations les plus importantes.
    • Commencez chaque phrase ou paragraphe avec les mots les plus importants et les points à retenir.
    • Lorsque vous expliquez un concept, commencez par la conclusion, puis expliquez-le plus en détail. (Cette méthode est parfois appelée « pyramide inversée ».)
    • Lors de l’explication d’un sujet complexe, présentez d’abord les informations de base aux lecteurs et dévoilez les détails plus loin dans l’article.
  • Utilisez des sous-titres explicites. Organisez les paragraphes associés en sections. Donnez à chaque section un sous-titre unique et qui décrit avec précision le contenu.
  • Envisagez d’utiliser des liens dans la page pour un contenu plus long. Cela permet aux lecteurs de passer à leurs centres d’intérêt et d’ignorer le contenu qui ne les intéresse pas.

Écrire à des fins de lisibilité

Facilitez la lecture et la compréhension du texte par les utilisateurs qui ont peu de temps.

  • Utilisez un langage simple. Utilisez des mots courants, du quotidien et évitez le jargon si possible. Vous pouvez utiliser des termes bien connus des développeurs, mais il est possible que le lecteur ne connaisse pas les détails de fonctionnement de GitHub.
  • Utilisez la voix active.
  • Soyez concis.
    • Écrivez des phrases simples et brèves.
    • Évitez les phrases complexes qui contiennent plusieurs concepts.
    • Réduisez les détails inutiles.

Pour plus d’informations, consultez la section « Voix et tonalité » dans Guide de style et Rédaction de contenu à traduire.

Mise en forme à des fins d’analyse

La plupart des lecteurs ne lisent pas les articles dans leur intégralité. Au lieu de cela, ils analysent la page pour rechercher des informations spécifiques, ou parcourent la page pour obtenir une idée générale des concepts.

S’ils analysent ou parcourent le contenu, les lecteurs ignorent les grands blocs de texte. Ils recherchent des éléments liés à leur tâche ou qui se distinguent sur la page, tels que les sous-titres, les alertes, les listes, les tables, les blocs de code, les visuels et les premiers mots de chaque section.

Une fois que l’article a un objectif et une structure clairement définis, vous pouvez appliquer les techniques de mise en forme suivantes pour optimiser le contenu pour l’analyse et le parcours. Ces techniques peuvent également aider à rendre le contenu plus compréhensible pour tous les lecteurs.

  • Utilisez la mise en surbrillance du texte, comme les caractères gras et les liens hypertexte, pour attirer l’attention sur les points les plus importants. Utilisez la mise en surbrillance du texte de manière éparse. Ne mettez pas en surbrillance plus de 10 % du texte total d’un article.
  • Utilisez des éléments de mise en forme pour séparer le contenu et créer de l’espace sur la page. Par exemple :
    • Listes à puces (avec des sous-titres d’accroche facultatifs)
    • Listes numérotées
    • Alertes
    • Tables
    • Objets visuels
    • Blocs de code et annotations de code

Pour aller plus loin