Guide de style

Approche de GitHub Docs relative au style

• Notre guide de style a pour objectif d'être simple. Les instructions doivent être faciles à appliquer à divers scénarios.
• Les décisions ne portent pas sur ce qu'il faut faire ou ne pas faire selon les règles de grammaire ou le guide de style, mais sur ce qui est le mieux pour nos utilisateurs. Nous sommes souples et ouverts au changement tout en gardant une certaine cohérence.
• Pour adapter le guide de style à mesure que notre équipe et nos documentations grossissent, et pour créer du contenu constructif de qualité au service des utilisateurs, nous concentrons notre attention sur des scénarios à fort impact et à forte valeur ajoutée plutôt que d'essayer de couvrir de manière exhaustive toutes les questions de style.
• La cohérence et la grammaire sont importantes, mais pas aussi importantes que la clarté et le sens.
• Lorsque nous prenons une décision de style ou de structure, nous prenons en compte le flux d'informations au sein de l'unité de contenu et le contexte des informations.
• Lorsqu'une question spécifique à la documentation de l'aide n'est pas couverte par le guide de style, nous y réfléchissons en appliquant ces principes, puis nous prenons une décision. Si un réviseur le demande, nous sommes prêts à discuter de la décision.

Événements du journal d'audit

Nous documentons chacun des événements susceptibles d'apparaître dans les journaux d'audit pour chaque type de compte : utilisateur, organisation et entreprise.

• Événements du journal de sécurité
• Événements du journal d’audit pour votre organisation
• Événements du journal d’audit pour votre entreprise

Lors de la rédaction de la description d'un événement de journal d'audit, décrivez l'événement qui s'est produit de façon à ce que cela s'applique à toutes les versions, en utilisant le passé et la voix passive. Ne commencez pas la phrase par des expressions déjà mentionnées dans le contexte de l'article, telles que « Déclenchée par ».

• Utiliser : La visibilité d'un dépôt a changé.
• Utilisation : L'analyse des secrets a été activée pour tous les nouveaux dépôts.
• Éviter : Le propriétaire d'organisation a désactivé l'authentification à deux facteurs qui était obligatoire dans l'organisation.
• Éviter : Déclenchée quand un utilisateur met à jour les dépôts auxquels un codespace peut accéder.

Alertes

Les alertes mettent l’accent sur les informations d’un article qui est d’une importance particulière et justifie la rupture du flux d’informations.

Utilisez les alertes avec parcimonie. N’utilisez pas d’alertes consécutives ou plusieurs alertes par section.

Les alertes doivent être concises. Si les informations se composent de plus d’un couple de phrases ou nécessitent une liste ordonnée ou non ordonnée, envisagez de les placer sous un titre de section à la place.

Types d’alertes

Nous utilisons cinq types d’alertes : note, conseil, important, avertissement et attention.

Remarque

Fournit un contexte supplémentaire que les utilisateurs peuvent avoir à prendre en compte. Les tâches peuvent être effectuées sans les informations contenues dans les alertes de remarque, mais certains utilisateurs dans certains contextes peuvent tirer parti de la remarque.

Les notes sont particulièrement utiles pour communiquer des informations entre parenthèses qui ne sont pas essentielles au processus décrit :

• Avertissements susceptibles d’affecter le résultat d’un processus, tels que des paramètres utilisateur spécifiques.
• Les produits et fonctionnalités dont la disponibilité est sujette à des changements, tels que ceux en préversion publique ou en cours de clôture.

Par exemple, Évaluation des alertes à partir de l’analyse des secrets utilise une note pour informer les utilisateurs que les métadonnées des jetons GitHub sont actuellement en préversion publique.

Conseil

Recommandations, meilleures pratiques ou conseils relatifs au produit. Les astuces contiennent des informations non essentielles que les utilisateurs peuvent suivre à leur discrétion. Elles sont particulièrement utiles dans les articles destinés aux nouveaux utilisateurs.

Par exemple, Personnalisez votre profil utilise une alerte de type astuce pour aider les utilisateurs à comprendre à quoi s’attendre lorsqu’ils @mention une organisation.

Important

Met en évidence les informations clés que les utilisateurs doivent connaître pour atteindre leur objectif.

Avertissement

Met en évidence les risques potentiels qu’un utilisateur doit connaître avant de commencer ou de poursuivre une tâche.

Les alertes d’avertissement sont particulièrement pertinentes pour les processus qui se produisent en dehors de l’IU GitHub, comme dans la ligne de commande ou via une API.

Par exemple, À propos des autorités de certification SSH inclut des instructions pour la ligne de commande et utilise une alerte d’avertissement pour informer les utilisateurs qu’une fois émis, les certificats ne peuvent pas être révoqués :

Attention

Alerte les utilisateurs des actions dangereuses ou destructrices qui doivent être effectuées avec une prudence extrême, en particulier lorsqu’il existe un risque de sécurité ou de perte de données.

Les alertes d’avertissement sont généralement nécessaires uniquement lors de la description des processus qui se produisent en dehors de l’IU GitHub, comme dans la ligne de commande ou via une API.

Mise en forme des alertes

Nous utilisons une mise en forme et des couleurs standard pour les différents types d'alerte qui apparaissent dans les documentations.

Les alertes sont affichées à l’aide de Markdown.

Remarque :

> [!NOTE]
> Keep this in mind.

Conseil :

> [!TIP]
> Here's a suggestion.

Avertissement :

> [!WARNING]
> Be careful.

Attention :

> [!CAUTION]
> Be extremely careful.

La syntaxe Liquid des alertes est toujours prise en charge et peut toujours apparaître dans les articles plus anciens, mais ne doit pas être utilisée pour les nouvelles alertes.

Pour plus d'informations sur la mise en forme des alertes, consultez « Alertes » dans Utilisation de Markdown et Liquid dans GitHub Docs.

Appel à l’action (CTA)

Un CTA est un lien ou un bouton qui invite les utilisateurs à passer à l’étape suivante de leur parcours. Il redirige l’utilisateur vers une autre page.

L’élément clé d’un CTA est qu’il aide l’utilisateur à accomplir ce qu’il cherche à réaliser, soit en le guidant vers l’étape suivante, soit en le dirigeant vers un produit ou une fonctionnalité dont il a besoin.

Pour déterminer quand utiliser un CTA, posez-vous les questions suivantes :

• Existe-t-il une étape suivante logique ou nécessaire pour l’utilisateur ? Il peut s’agir des prochaines informations dont il a besoin, ou d’une fonctionnalité qui l’aidera à accomplir sa tâche.
• Existe-t-il un besoin commercial qui justifie de rediriger l’utilisateur vers cet endroit ?

Il ne faut utiliser un CTA que lorsque la réponse aux deux questions est oui.

En quoi un CTA diffère-t-il d’un lien ?

Un CTA donne une instruction explicite à l’utilisateur pour qu’il effectue une action immédiate, telle que « Essayez Copilot gratuitement » ou « Créez votre propre référentiel ». Dans notre documentation, un CTA doit uniquement rediriger les utilisateurs vers un domaine appartenant à GitHub.

Par exemple, le CTA sur Configuration d’une version d’évaluation de GitHub Enterprise Cloud renvoie à une page de vente de l’entreprise sur GitHub.com.

Création de CTA

Pour créer une URL de CTA valide avec les paramètres corrects, utilisez le script de création de CTA dans votre référentiel de documentation local :

npm run cta-builder

Le script vous guide tout au long d’un processus interactif pour :

• Sélectionnez le produit GitHub approprié (ref_product)
  • Utiliser github comme valeur par défaut lorsque le lien n’est pas spécifique à une fonctionnalité ou un produit particulier
• Choisir le type d’action (ref_type)
• Spécifier le style de mise en forme (ref_style)
• Sélectionnez éventuellement un plan spécifique (ref_plan)

Le script fournit toutes les options disponibles pour chaque paramètre et génère une URL CTA complète et valide à la fin. Utilisez cet outil pour vous assurer que vous utilisez des valeurs actuelles et approuvées pour les paramètres CTA.

Par exemple, le script peut générer une URL telle que :

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

Code

Blocs de code

Dans les exemples de code, comptez environ 60 caractères sur chaque ligne pour éviter aux lecteurs d'avoir à faire défiler horizontalement le bloc de code. Placez le texte explicatif avant le bloc de code, plutôt que d'utiliser des commentaires au sein du bloc de code. Pour plus d'informations sur la syntaxe et la mise en forme des blocs de code, consultez Utilisation de Markdown et Liquid dans GitHub Docs.

Dans les blocs de code :

• Spécifiez le langage de l'exemple après la première clôture de code. Pour obtenir la liste de tous les langages pris en charge, consultez Langages de code dans le référentiel github/docs.

• N'utilisez pas de code HTML pour ajouter un style ou une balise à un bloc de code.

• Mettez en majuscules tous les espaces réservés que les utilisateurs doivent remplacer par leurs propres valeurs. * Utilisez :git checkout -b BRANCH-NAME * Éviter :git checkout -b <branch-name>

• N'utilisez pas d'invite de commandes comme $ avant la commande elle-même. Ces invites compliquent la tâche des lecteurs de copier et coller la commande.

  • Si vous affichez une commande et la sortie de la commande, commentez la sortie dans l'exemple.

  •       **Utiliser :**
    

    command
    # output
    

  •       **Éviter :**
    

    $ command
    output
    

• Si votre exemple de code comprend { ou } et qu'elles doivent être restituées, enveloppez cette section entre {% raw %}{% endraw %} afin de désactiver le traitement Liquid pour cette section. * Utiliser :

    GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    

  •       **Éviter :**
    

    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    

• Si votre exemple de code contient du contenu qui doit être interprété, entourez cette section avec les balises <pre>``</pre> afin que le contenu soit analysé plutôt qu’échappé.

Commandes

Utilisez des blocs de code inline pour faire référence à des noms de commande courts.

• Utiliser : Pour vérifier l'état d'un cluster en cours d'exécution, utilisez la commande ghe-cluster-status.

Utilisez des blocs de commandes pour les commandes plus longues ou plus complexes.

• Utiliser : Activez le mode maintenance en fonction de votre fenêtre planifiée en vous connectant à l'interpréteur de commandes d'administration d'un nœud de cluster et en exécutant :

  ghe-cluster-maintenance -s
  

N'incluez pas d'invites de commandes telles que $. Évitez les liens inline dans les noms de commande.

Sorties

Si vous affichez la sortie d'une commande, commentez la sortie dans l'exemple afin que les personnes puissent copier et coller la commande et l'exécuter sans modification.

• Utiliser :

  git lfs install
  # Git LFS initialized.
  

• Éviter :

  $ git lfs install
  > Git LFS initialized.
  

Exemples

Lorsque les exemples de code font référence à un fichier plus long, montrez la section appropriée du fichier afin que les utilisateurs comprennent comment modifier leur propre code en contexte.

• Utiliser :

on:
  schedule:
    - cron:  "40 19 * * *"

• Éviter :

schedule:
  - cron:  "40 19 * * *"

Noms de fichiers et d'annuaires

Utilisez des backticks pour formater les références aux noms de fichiers et de répertoires avec une police monospace. Si un type de fichier suit généralement une convention de mise en majuscules spécifique, telle que le tout en majuscules pour les fichiers README, utilisez la convention établie.

• Utiliser : Dans votre fichier README.md, ajouter des informations sur votre dépôt.
• Utiliser : Dans votre répertoire .github/workflows/, créer le fichier example-workflow.yml.
• Éviter : Dans votre répertoire .github/workflows/ , créer le fichier example-workflow.yml.
• Éviter : Supprimez le fichier example.js.

Indentation

Dans les exemples YAML, comme les actions et les fichiers de workflow, utilisez deux espaces pour mettre en retrait les lignes dans les listes imbriquées et les séquences de blocs.

• Utiliser :

    steps:
      - uses: actions/checkout@v5
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

Pour mettre en retrait les éléments réutilisables, consultez data/reusables/README.md.

Workflows planifiés

Les exécutions de workflows prennent du retard lorsque trop de workflows s'exécutent à la fois. Étant donné que de nombreux utilisateurs copient du code à partir de GitHub Docs, nous devons utiliser des exemples qui évitent les heures surchargées aux utilisateurs.

• N’utilisez pas d’exemples exécutés à l’heure pile, car ce sont les moments les plus saturés.
• N’utilisez pas d’exemples qui s’exécutent plus souvent que nécessaire. Par exemple, au lieu d'exécuter un exemple toutes les cinq minutes, déterminez s'il n'est pas plutôt judicieux de l'exécuter toutes les trente minutes.
• Utilisez une heure différente pour chaque exemple.

Emphase

Utilisez le gras pour mettre en évidence des mots ou des parties d'une phrase. Utilisez l’accentuation avec modération (pas plus de cinq mots contigus), et n’oubliez pas qu’il s’agit d’une aide visuelle pour la lecture rapide des utilisateurs voyants.

• N'utilisez pas le gras pour des mots auxquels d'autres mises en forme sont appliquées, telles que le format tout en majuscules pour le texte des espaces réservés.
• Pour des raisons d’accessibilité, n’utilisez pas le texte en gras comme seul moyen de transmettre une signification ou une mise en évidence.

Par exemple :

• Utilisation : les comptes d’utilisateur managés ne peuvent pas créer de contenu public ou collaborer en dehors de votre entreprise.
• Éviter : À côté de Titre, ajoutez un nom descriptif pour votre nouvelle clé.

Messages d'erreur

Lorsque vous incluez le texte d'un message d'erreur à partir d'un produit ou d'une interface GitHub dans un article, mettez en forme le texte en fonction de l'interface où le message s'affiche.

• Si le message apparaît dans l'interface web de GitHub ou dans une application client graphique comme GitHub Desktop ou GitHub Mobile, traitez le message comme tout autre texte dans l'interface utilisateur. Pour en savoir plus, consultez Texte d'interface utilisateur.

• Si le message apparaît dans une interface de ligne de commande, une sortie de journal ou une réponse d'une API, reproduisez le texte à l'identique et utilisez des crochets pour formater le message à l'aide d'une police monospaciale.

Contenu expirant

De manière générale, il convient de ne pas documenter un contenu qui arrivera à expiration. Tout visiteur du site GitHub Docs doit pouvoir être certain que les informations qui y figurent sont exactes et à jour.

Si vous devez documenter un contenu susceptible d'expirer, utilisez l'indicateur du linter de contenu pour baliser et suivre la date d'expiration du contenu. Ainsi, le contenu sera signalé comme obsolète et vous n'aurez pas à vérifier les dates d'expiration en dehors du contenu lui-même. Pour plus d'informations sur la mise en forme des balises de contenu arrivant à expiration, consultez Utilisation de l'analyseur de contenu.

Notes de bas de page

Évitez d'utiliser des notes de bas de page si possible. Essayez plutôt de voir si vous pouvez utiliser une alerte ou présenter les informations d'une autre manière. Découvrez quelques exemples d'alternatives aux notes de bas de page sur NICE.org.uk.

Si vous devez utiliser des notes de bas de page, utilisez des notes de bas de page propres à Markdown ([^1]). Les marqueurs de note de bas de page seront mis en lien hypertexte vers la référence de note de bas de page, qui sera listée en bas de la page avec un lien retour vers le marqueur.

Notez que quel que soit l'identificateur que vous utilisez (lettres, mots), les notes de bas de page s'affichent sous forme de nombres séquentiels.

          [^1]: Not to be confused with Davy Jones of The Monkees

          [^2]: Also humans

| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

Titres de section

Les titres de section doivent décrire correctement le contenu qui les suit. Les en-têtes peuvent suivre les instructions pour écrire des titres ou être écrits en tant que questions. Utilisez la casse de phrase pour les en-têtes.

Si un article a des en-têtes, ceux-ci doivent commencer par un en-tête de niveau H2. Vous pouvez utiliser des en-têtes de niveau H3 et H4 pour organiser davantage le contenu en groupes associés, mais vous ne pouvez pas ignorer les niveaux d'en-tête. Vous devez avoir du contenu de texte entre un titre de section et un titre de sous-section, par exemple une introduction.

• Utiliser :

  ## HEADER (H2)
  
  TEXT
  
  ### SUBHEADER (H3)
  
  TEXT
  
  #### SUBHEADER (H4)
  
  TEXT
  

• Éviter :

  ## HEADER (H2)
  
  #### SUBHEADER (H4)
  

Dans une page, chaque titre de section au même niveau doit être unique.

• Utiliser :

  ## Examples  (H2)
  
  TEXT
  
  ### Prompts for writing code (H3)
  
  TEXT
  
  ### Prompts for writing tests (H3)
  
  TEXT
  

• Utiliser :

  ## Prompts for writing code (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ## Prompts for writing tests (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

• Éviter :

  ## Example prompts (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

Images

Nous utilisons des images statiques, notamment des captures d'écran, des diagrammes et des graphiques, dans la documentation pour compléter le texte.

N'utilisez pas de GIF animés dans la documentation.

Texte de remplacement

Chaque image doit inclure un texte de remplacement qui fournit l'équivalent des informations visuelles.

• Exprimez l'idée ou le sens clé de l'image, plutôt que de la décrire littéralement.
• Utilisez entre 40 et 150 caractères.
• Terminez par un signe de ponctuation. Il s’agit généralement d’un point, sauf si le texte de remplacement décrit une image illustrant du texte qui se termine par un autre signe de ponctuation, comme un point d’interrogation ou un point d’exclamation.
• Ne commencez pas par « Image… » ou « Graphique… ». Les lecteurs d'écran le disent automatiquement.
• Commencez par le type d’image : « Capture d’écran de… » ou « Diagramme montrant… »
• Suivez le langage standard utilisé pour décrire les éléments de l'interface utilisateur dans le texte de l'article.
• Placez les titres qui se composent de plusieurs mots, tels que les noms des éléments de menu, entre chevrons (« »).
• Si une partie de l'image est visuellement mise en évidence, décrivez comment elle l'est. Cela permet aux utilisateurs de lecteurs d'écran de comprendre et de décrire à un ami ou un collègue voyant ce qu'ils doivent observer du point de vue du langage visuel.

Texte de remplacement pour les captures d'écran

Le texte de remplacement fournit une brève description du contenu d'une capture d'écran pour les personnes qui ne peuvent pas la voir.

• Le texte de remplacement doit uniquement contenir les éléments les plus intéressants d'une image, pas chaque détail.
• Le texte de remplacement n'est pas destiné à fournir des instructions pour utiliser l'interface GitHub. Celles-ci doivent être comprises dans le texte de l'article qui l'accompagne.

Format

Capture d'écran de Product name + UI element. UI element + state of the element/controls, et keyboard shortcut XYZ, sont encadrés en orange foncé.

• Pour Product name, utilisez le nom du produit ou de la fonctionnalité de GitHub, tel que « GitHub Actions » ou « répertoire GitHub », plutôt que simplement « GitHub ».
• Utilisez une variable pour le mot GitHub, comme nous le faisons actuellement : {% data variables.product.prodname_dotcom %}
• Décrivez les éléments d'interface utilisateur en restant cohérent avec la documentation écrite.
• Soyez souple avec l'ordre des mots si besoin par souci de clarté.
  • Par exemple, écrivez « Capture d’écran du menu Débogage dans Visual Studio Code… » plutôt que « Capture d’écran du menu Débogage Visual Studio Code… » pour éviter plusieurs noms dans une ligne.

Exemples

Capture d’écran du tableau des commiteurs GitHub par dépôt. L’icône des trois points horizontaux et le bouton « Télécharger le rapport CSV » sont encadrés en orange foncé.

Capture d'écran des options de fichier dans un dépôt GitHub. Un bouton avec une flèche indiquant un menu déroulant, intitulé « Code », est indiqué en orange foncé.

Texte de remplacement pour les diagrammes et les graphiques

Expliquez les informations véhiculées par le diagramme ou le graphique dans le texte de la page.

Utilisez un texte de remplacement pour exprimer l'idée clé de l'image, sans répéter le texte de la page web.

Exemple

Diagramme montrant une procédure en cinq étapes via laquelle un exécuteur GitHub Actions peut être automatiquement ajouté à des classes nommées d'exécuteurs, puis demandé par des travaux spécifiques.

Par exemple, consultez l'explication qui accompagne ce diagramme dans la documentation Actions.

Texte de remplacement pour les images des interfaces de ligne de commande

N'utilisez pas de captures d'écran des interfaces de ligne de commande pour illustrer les commandes et leur sortie. Fournissez plutôt directement les commandes que l'utilisateur doit utiliser. Pour plus d’informations, consultez la section Commandes du guide de style.

Lorsque vous utilisez une capture d'écran d'une interface de ligne de commande pour montrer des éléments d'interface utilisateur, suivez les instructions de texte de remplacement standard pour les captures d'écran.

Noms de fichiers pour les images

Soyez descriptif lorsque vous nommez les fichiers image : incluez le nom, l'action et l'élément d'IU dans le nom de fichier. Reflétez le langage du produit. Utilisez la casse kebab. N'utilisez pas de conditionnels Liquid dans les noms de fichier. Si vous remplacez une image, utilisez le nom de fichier exact.

• Utilisez :data-pack-purchase-button.png
• Éviter :purchase_button.png
• Éviter :purchase-button-for-admins.png

Captures d'écran

Pour en savoir plus sur la création et le contrôle de version des images, consultez Création et mise à jour de captures d’écran.

Schémas

Pour en savoir plus sur la création de diagrammes, consultez Création de diagrammes pour GitHub Docs.

Langage inclusif

Réunissant la plus grande communauté de développeurs au monde, GitHub s'engage à promouvoir la diversité et l'inclusion dans toutes nos actions. Toute notre documentation est inclusive et respectueuse de notre audience, qui se compose de personnes du monde entier qui viennent d'horizons très différents. Lorsque nous rédigeons notre documentation, nous utilisons des mots inclusifs, antiracistes et accessibles.

Les mots utilisés seuls peuvent sonner creux, mais mis ensemble, ils peuvent créer une communauté, une appartenance et une équité. Faites preuve d'empathie dans tous vos choix de mots et de styles. Soyez précis lorsque vous faites référence à des personnes et des communautés.

Ressources sur le langage inclusif

Le Guide de style Microsoft offre des ressources sur la communication sans biais, la terminologie d'accessibilité et l'écriture pour tous :

• Communication sans biais
• Écriture pour toutes les capacités
• Terminologie d'accessibilité

Autres ressources pour en savoir plus sur le langage et le style inclusifs et accessibles :

• Guide de style du contenu MailChimp : * Écriture sur les personnes * Écriture pour l’accessibilité
• Recommandations en matière de lisibilité
• Guide de style conscient

Raccourcis clavier

Pour présenter les raccourcis clavier, suivez le Guide de style de Microsoft, à l'exception des différences suivantes :

• Utilisez la balise HTML <kbd> pour chaque touche.

  •       **Utilisez :**`<kbd>Command</kbd>+<kbd>B</kbd>`
    

  •       **Éviter :**`Command+B`
    

• Utilisez des mots complets plutôt que des symboles pour les touches de modification Apple.

  •       **Utilisez :**`Command`
    

  •       **Éviter :**`⌘`
    

• Utilisez des symboles pour les touches des caractères spéciaux, pas les mots entiers.

  •       **Utiliser :**`.`, `,` et `→`.
    

  •       **Éviter :**`Period`, `Comma` et `Right arrow`.
    

Principaux usages

Voici quelques points importants concernant la manière dont nous présentons les raccourcis clavier dans notre documentation :

• La syntaxe de base consiste à montrer les touches avec + entre les combinaisons de touches, sans espaces.

  •       **Utiliser :**`<kbd>Command</kbd>+<kbd>B</kbd>`, qui apparaît comme ceci : <kbd>Command</kbd>+<kbd>B</kbd>.
    

  •       **Éviter :**`<kbd>Command</kbd> + <kbd>B</kbd>` ou `<kbd>Command + B</kbd>`, qui apparaissent comme ceci : <kbd>command</kbd> + <kbd>B</kbd> ou <kbd>Command + B</kbd>.
    

• Mettez toujours en majuscules les touches de lettre pour les références générales et les raccourcis clavier.

  •       **Utiliser :**<kbd>Commande</kbd>+<kbd>B</kbd>
    

  •       **Éviter :**<kbd>Commande</kbd>+<kbd>b</kbd>.
    

• Utilisez les touches de modification appropriées pour chaque système d'exploitation.

          **Remarque :**<kbd>Ctrl</kbd> apparaît en abrégé sur Windows et Linux, alors qu'il apparaît en entier sur Mac : <kbd>Contrôle</kbd>.
  

  • Pour Windows et Linux :

    •     **Utiliser :**<kbd>Ctrl</kbd>, <kbd>Alt</kbd>.
      

    •     **Éviter : **<kbd>Contrôle</kbd>
      

  • Pour Mac :

    •     **Utiliser :**<kbd>Commande</kbd>, <kbd>Option</kbd>, <kbd>Contrôle</kbd>.
      

    •     **Éviter :**<kbd>Cmd</kbd>, <kbd>⌘</kbd>, <kbd>Opt</kbd>, <kbd>⌥</kbd>, <kbd>Ctrl</kbd>, <kbd>⌃</kbd>
      

• Ne confondez pas les combinaisons de touches avec les touches dans une séquence.

  •       <kbd>Commande</kbd>+<kbd>B</kbd> indique que l'utilisateur doit maintenir la touche <kbd>Commande</kbd> enfoncée et appuyer sur la touche <kbd>B</kbd>.
    

  •       <kbd>G</kbd><kbd>I</kbd> indique que l'utilisateur doit appuyer sur la touche <kbd>G</kbd>, puis sur la touche <kbd>I</kbd>.
    

• Lorsque vous décrivez un raccourci clavier pour plusieurs systèmes d'exploitation, ajoutez le système d'exploitation entre crochets après le raccourci. Décrivez d'abord le raccourci Mac, puis Windows/Linux.

  •       **Utiliser :**`<kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)`, qui apparaît comme ceci :
    
    
          <kbd>Commande</kbd>+<kbd>B</kbd> (Mac) ou <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows / Linux)
    

  •       **Éviter :**`<kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>`, qui apparaît comme ceci :
    
    
          <kbd>Ctrl</kbd>+<kbd>B</kbd> ou <kbd>Commande</kbd>+<kbd>B</kbd>
    

Contenu sous licence

GitHub Docs est concédé sous une licence CC-BY. Si vous réutilisez ou modifiez du contenu sous licence dans un article, vous devez vous assurer que la licence est compatible et correctement attribuée.

Ne créez pas d'éléments réutilisables pour les attributions de licences. Nous devons utiliser la licence exacte sous laquelle un projet est concédé, c'est pourquoi toute attribution mentionnée dans des articles doit être correcte.

Si vous ne savez pas trop si la réutilisation d'un contenu est légale, contactez le service juridique. Si vous ajoutez du contenu avec une licence qui ne figure pas ici, vous devez obtenir un examen juridique avant de pouvoir publier ce contenu.

Attribution de contenu sous licence MIT

Si nous réutilisons ou modifions du contenu sous une licence MIT, nous devons attribuer la licence MIT où le contenu apparaît.

À la fin de l'article contenant le contenu sous licence MIT

• Créer un titre de section Legal notice
• Préciser d'où vient le contenu et indiquer qu'il est concédé sous licence MIT. Inclure un lien vers le projet
• Coller l'intégralité du texte de la licence MIT du projet que vous attribuez dans un bloc de code

Exemple d'attribution de licence MIT

Ce texte est juste un exemple. Utilisez toujours le texte de la licence du projet que vous attribuez.

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

Sauts de ligne

Pour le texte brut, utilisez des sauts de ligne pour séparer les paragraphes dans la source (deux sauts de ligne consécutifs), plutôt que pour créer un espace visuel dans la source. Évitez les sauts de ligne inutiles, en particulier dans les listes.

Liens

Les liens sont utilisés pour rediriger les personnes vers des informations supplémentaires et pour progresser dans les tâches qui nécessitent la lecture de plusieurs articles.

          **Faites preuve de modération avec les liens.** Inclure trop de liens peut distraire ou déconcentrer les personnes du contenu principal. Tous les liens doivent être pris en compte dans le contexte du parcours utilisateur : pourquoi diriger la personne vers ce lien et comment la recentrer sur sa tâche ?

Avant d’ajouter un lien, décidez si la personne doit consulter le lien pour comprendre le contenu ou réussir à utiliser GitHub.

• Si le lien n’est pas nécessaire, supprimez-le.
• Si le lien concerne le sujet principal d’un article et permet à la personne de continuer à apprendre, mais n’est pas nécessaire pour réaliser la tâche, envisagez de déplacer le lien vers la fin de l’article afin de le suggérer comme une lecture pour aller plus loin.
• Si le lien dirige une personne à l’étape suivante d’un processus, incluez le lien dans une section Étapes suivantes à la fin de l’article.
• Si le lien fournit des informations qui peuvent être essentielles à la réalisation d’une tâche ou à la résolution d’une étape, incluez le lien dans le corps principal de l’article.

Les liens doivent être cohérents, accessibles au plus grand nombre, traduisibles et compréhensibles. Les internautes ont besoin de savoir à quoi mène un lien et quel est son rapport avec ce qu'ils veulent accomplir.

Quelques bonnes pratiques pour utiliser des liens :

• Les liens doivent apporter du sens et une grande valeur ajoutée au parcours utilisateur. Créez des liens externes avec soin.
• N’ajoutez pas le même lien plusieurs fois dans le même article.
• Envisagez d’ajouter « plus loin dans cet article » après un lien vers une section du même article.
• N'incluez pas le paramètre de requête apiVersion dans les liens REST, sauf si vous devez créer un lien vers une version de calendrier spécifique de la documentation REST. (Ce devrait être rare.)

Mise en forme des liens

Vous pouvez introduire des liens avec le seul verbe « voir » si le contexte indique clairement l’objet du lien. Si le contexte n'est pas clair, utilisez une expression ou une phrase pour introduire le lien, telle que « Pour plus d'informations, consultez » ou « Pour en savoir plus sur X, consultez Y .»

Utilisez le titre de l'article de la documentation ou de la page Web externe comme texte du lien. Pour tout lien pointant vers un autre article sur le site GitHub Docs, utilisez le mot clé spécial AUTOTITLE pour le texte du lien. Consultez les détails dans la référence de balisage du contenu.

N’appliquez pas de style aux liens et ne les mettez pas entre guillemets.

• Pour les liens vers d'autres pages : See [AUTOTITLE](/PATH/TO/PAGE).
• Pour les liens vers des sections dans d'autres pages : For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

N'utilisez pas de liens inclus, où les mots contenus dans la phrase sont liés par un lien hypertexte sans aucun autre mot pour indiquer que la phrase contient un lien. Cela peut être difficile à traduire et à lire.

N’incluez pas de signes de ponctuation dans un lien hypertexte.

• Utilisez :OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).
• Éviter :Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.

Liens entre les versions

Parfois, vous devez établir un lien d’une version de GitHub Docs à une autre. Lorsque vous souhaitez créer un lien vers une autre version de la même page, vous devez utiliser la propriété currentArticle.

Par exemple, les versions Free, Pro et Team de Gestion de la publication de sites GitHub Pages pour votre organisation peuvent renvoyer à la version GitHub Enterprise Cloud du même article comme suit :

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

Pour créer un lien vers un autre article d'une autre version, utilisez ce format :

For more information, see [ARTICLE TITLE](/) in the VERSION documentation.

Pour créer un lien vers le même article d'une autre version, utilisez ce format :

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

Pour créer un lien vers une version spécifique, vous devez inclure la version dans le chemin (par exemple, /enterprise-cloud@latest/{{ currentArticle }}).

Liens vers des sections spécifiques d'articles

Les liens vers des sections spécifiques d’articles doivent être suffisamment descriptifs pour que la personne comprenne qu’elle se trouve au bon endroit après avoir suivi un lien.

Pour créer un lien vers un titre de section spécifique du même article, utilisez ce format :

For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article.

Les liens vers des sections de la même page ne fonctionnent pas avec AUTOTITLE. Au lieu de cela, vous devez taper le titre d’en-tête en entier.

Pour créer un lien vers un titre de section spécifique d'un autre article, utilisez ce format :

For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE).

Pour créer un lien vers plusieurs titres de section spécifiques d'un autre article, utilisez ce format :

For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE."

Liens vers un outil spécifique

Si vous créez un lien vers du contenu avec un outil spécifique sélectionné, assurez-vous que le lien sera destiné à un outil spécifique même si la personne n’interagit pas avec l’onglet de sélection d’outils dans l’article.

For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME).

Liens vers les parcours d'apprentissage

Utilisez ce format pour créer un lien vers un parcours d'apprentissage.

For more information, follow the [LEARNING PATH TITLE](/) learning path.

Liens vers des ressources externes

Lors de la liaison à un site externe, choisissez la ressource la plus utile pour le contexte du lien. Vous pouvez créer un lien vers un site entier s’il s’agit d’une référence générale ou vers une page spécifique si cela est plus utile.

Il n'est pas nécessaire de créer un lien vers le site web d'un produit externe lorsque nous mentionnons un produit externe.

Pour les liens vers une page externe (tout site web qui n’est pas géré par GitHub), tapez le titre de page complet et le site de destination. Ne mettez pas le lien entre guillemets.

• Utilisez :See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.
• Éviter :See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).
• Éviter :See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).

Ajout d'ancres pour conserver des liens

Si vous savez qu'il existe des liens qui pointent vers une section spécifique d'un article, vous pouvez lui ajouter une ancre pour assurer leur bon fonctionnement. Par exemple, si une ressource externe est liée à une section spécifique d'un article, vous pouvez ajouter une ancre afin que le lien pointe directement vers la bonne section, même si son titre change.

Utilisez ce format pour les ancres de lien. Le nom de l'ancre doit correspondre au nom de la section qui est conservée. Utilisez un commentaire HTML pour expliquer pourquoi vous ajoutez l'ancre.

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

Listes

Mettez en majuscules la première lettre de chaque ligne d'une liste. Utilisez des points à la fin des lignes d'une liste seulement si celles-ci contiennent une phrase complète.

Lorsque vous dressez une liste d'éléments qui se composent d'un texte principal et d'un texte secondaire, comme un term et sa définition, utilisez le signe deux points. Le texte secondaire doit commencer par une majuscule comme si c'était le début de la ligne. Par exemple :

• foo : Élément qui fournit bar.
• bar : Élément fourni par foo.

Mise en forme des listes sans ordre particulier :

• Si l'ordre des éléments de la liste n'est pas important, classez les éléments de liste par ordre alphabétique.
• Si l'ordre est important, triez la liste en fonction de l'importance que cela représente pour le lecteur (par exemple, passer du public le plus large à un public plus spécialisé).
• Utilisez des astérisques (*) pour les éléments de liste.

Lors de l'introduction d'une liste, évitez les phrases courtes et non spécifiques qui utilisent des termes comme « suivant(e)(s) » ou « ces », qui sont difficiles à localiser sans contexte. Au lieu de cela, créez une phrase descriptive qui exprime clairement le sujet de la liste, tout en permettant à la liste d'évoluer ou de changer sans avoir à mettre à jour la description.

          **Utiliser :**

• Pour une présentation de GitHub, consultez les articles suivants :

• L'authentification par SMS est prise en charge dans ces pays :

          **Éviter :**
  

• Il existe plusieurs articles qui fournissent une introduction aux données GitHub. Consultez ce qui suit :

• L'authentification par SMS est prise en charge dans 50 pays. Il s’agit notamment des paramètres suivants :

Instructions d’autorisations et encadrés produits

Utilisez des instructions d’autorisation et des encadrés de produit pour communiquer les tâches dont l’exécution nécessite des rôles ou des produits spécifiques.

• Déclarations d'autorisations : rôle requis pour effectuer une action ou une tâche décrite dans l’article. Exemple : « Propriétaires d'entreprises ».
• Mise en avant du produit : le ou les produits nécessaires pour effectuer une action ou une tâche décrite dans l’article. Exemple : « Comptes d’organisation et d’entreprise avec un abonnement à Copilot Business ».

Ensemble, les déclarations d'autorisation et les mentions des produits indiquent aux lecteurs qui peut utiliser la fonction décrite dans un article.

Bonnes pratiques pour créer des encadrés produits faciles à parcourir.

Définir les autorisations par rapport aux exigences du produit

Réfléchissez aux informations qui doivent figurer dans une instruction d’autorisation ou dans un encadré produit.

Par exemple, lors de la création d’autorisations et de listes de produits pour l'article Gestion des stratégies et des fonctionnalités pour GitHub Copilot dans votre organisation, la déclaration d’autorisation répondrait à la question suivante : « Quel rôle peut gérer les stratégies et les fonctionnalités de GitHub Copilot au sein d'une organisation ? » Et la fiche produit répondrait à la question suivante : "De quels Copilot abonnements les utilisateurs ont-ils besoin pour gérer Copilot les politiques et les fonctionnalités d'une organisation ?"

Concentrez-vous sur les informations clés, et non sur les explications

Les déclarations d'autorisation et les appels de produits doivent indiquer qui peut effectuer une tâche et quel produit est nécessaire. Ils n'ont pas besoin d'expliquer pourquoi un rôle ou un produit est nécessaire.

Si plusieurs rôles ou produits s’appliquent à une déclaration d’autorisation ou à un encadré de produit, mettez-les en forme à l’aide d’une liste non ordonnée. Vous pouvez introduire des déclarations d’autorisation complexes et des mises en avant de produit par une phrase, mais essayez toujours d’utiliser le moins de mots possible pour indiquer qui peut faire ce dont traite l'article.

Utilisez des liens en ligne

Vous pouvez utiliser des liens en ligne pour fournir plus d'informations sur un rôle ou un produit. Le texte du lien doit correspondre à la destination du lien, de sorte que l'on sache clairement à quoi le lien mène.

Espaces réservés

Mettez en majuscules tout texte de remplacement. Si un espace réservé comporte plusieurs mots, reliez-les avec des tirets (kebab-case). Si vous utilisez un espace réservé, expliquez par quoi quelqu'un pourrait le remplacer. Cela permet aux utilisateurs de modifier des exemples pour répondre à leurs besoins et d'identifier les espaces réservés pour les personnes qui utilisent la technologie d'assistance.

          **Utiliser :**

• Dans l'exemple suivant, remplacez YOUR-REPOSITORY par le nom de votre référentiel. git init YOUR-REPOSITORY

• Cliquez sur Add USERNAME. Où USERNAME est le nom d'utilisateur de la personne que vous souhaitez ajouter.

          **Éviter :**
  

• git init your repository

• git init <your-repository>

• Cliquez sur Add Username.

Procédures

Les procédures fournissent aux lecteurs un ensemble d'étapes séquentielles à suivre pour accomplir une tâche. Utilisez toujours des listes numérotées pour les procédures. Fournissez aux lecteurs tous les prérequis ou informations conceptuelles dont ils auront besoin pour effectuer la tâche avant la procédure, plutôt que de les inclure dans une étape spécifique.

Chaque étape doit inclure une action. Vous pouvez également choisir d'indiquer si une étape est facultative, d'expliquer la raison ou le résultat de l'étape et d'orienter le lecteur en décrivant où se situe l'action, avant de le guider pour la réaliser.

Utilisez un ordre cohérent pour présenter les informations dans chaque étape.

1. Si l'étape est facultative, commencez par l'indiquer.

2. Pour des raisons de clarté ou pour insister sur la gravité d'une action destructrice ou équivoque, expliquez la raison ou le résultat de l'étape si nécessaire.

3. Décrivez où l'utilisateur trouvera l'action.

4. Action.

          **Utilisez :** Si vous le souhaitez, pour `REASON`, dans `LOCATION`, prenez `ACTION`.
   

Exemples :

• Cliquez sur Informations de paiement.
• Sous le nom de votre organisation, cliquez sur Paramètres.
• Pour confirmer votre changement, cliquez sur Supprimer la carte de crédit.
• Éventuellement, pour voir les détails de votre plan, cliquez sur Afficher les détails.
• Sous « GitHub Sponsors », à droite du contributeur open source parrainé, cliquez sur en regard de votre montant parrainé, puis cliquez sur Modifier le niveau.

Noms de produits

Utilisez les noms de produit entiers. N'abrégez pas ou ne raccourcissez pas les noms de produit à moins de reproduire directement le contenu du produit (exemple : des réponses d'API). Les noms des produits ne sont jamais possessifs.

Utilisez des variables de nom de produit pour restituer les noms des produits. N’écrivez pas les noms des produits en texte brut. Cela facilite l'implémentation des changements de nom de produit sur l'ensemble du site et cela évite les fautes de frappe dans les noms de nos produits. Pour plus d’informations sur les variables de nom de produit, consultez « Éléments réutilisables et variables » dans ce document et le répertoire de données du dépôt github/docs.

Les noms de produit sont toujours au singulier.

• Utiliser : GitHub Actions vous permet d'automatiser vos workflows de développement logiciel.
• À éviter : Les GitHub Actions vous aident à automatiser vos workflows de développement logiciel.

Veillez à faire la distinction entre les noms de produit et les caractéristiques du produit. Les caractéristiques du produit sont toujours en minuscules.

Ne mettez pas de majuscules aux fonctionnalités courantes comme pull requests, topics ou issues.

Conventions spécifiques au produit

Cette section décrit des conventions supplémentaires spécifiques aux produits GitHub.

GitHub Actions

Éléments réutilisables pour les actions internes

Les exemples de code qui utilisent des actions internes doivent utiliser l’élément réutilisable respectif pour cette action. Cela facilite la gestion des mises à jour des versions d'actions (par exemple, de v1 à v2) pour des produits tels que GitHub Enterprise Server qui risquent de ne pas avoir la même version d'action disponible jusqu'à une version ultérieure de GitHub Enterprise Server.

Les actions réutilisables se trouvent dans /data/reusables/actions/ et ont un nom de fichier du type action-<action_name>.md

Par exemple, pour utiliser l’action actions/checkout dans un exemple, utilisez son élément réutilisable :

steps:
  - name: Checkout
    uses: actions/checkout@v5

Pour GitHub Docs, une action interne est toute action ayant le préfixe actions/, github/ ou octo-org/. Par exemple, voici une action interne :

steps:
  - uses: actions/checkout@v5

Exclusions de responsabilité pour les actions tierces

Les exemples de code qui utilisent des actions tierces doivent inclure l'exclusion de responsabilité suivante dans le cadre du bloc de code :

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

Pour insérer cette exclusion de responsabilité, utilisez l'élément réutilisable {% data reusables.actions.actions-not-certified-by-github-comment %}.

Pour GitHub Docs, une action tierce est toute action sans le préfixe actions/, github/ ou octo-org/. Par exemple, voici une action interne :

steps:
  - uses: actions/checkout@main

Voici un exemple d'action tierce :

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Exemples :

• Consultez le bloc de code dans Publication sur des registres de packages

Épinglage des numéros de version dans un SHA

Les exemples de code qui utilisent des actions tierces doivent toujours être épinglés à un SHA de commit complet, au lieu du numéro de version ou de la branche :

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Pour GitHub Docs, une action tierce est toute action qui n'a aucun des préfixes suivants : actions/, github/ et octo-org/. Par exemple, voici une action interne :

steps:
  - uses: actions/javascript-action@main

Pour plus d’informations, consultez Utilisation de SHA

Codespaces

Lorsque vous faites référence au produit Codespaces, incluez toujours « GitHub », sauf dans les circonstances suivantes :

• Dans les notes liminaires shortTitle.
• Dans les sous-titres d'un article, si « Codespaces » a déjà été utilisé quelque part dans l'article avant le sous-titre.

Variables : {% data variables.product.prodname_github_codespaces %} (« GitHub Codespaces ») et {% data variables.product.prodname_codespaces %} (« Codespaces »).

Lorsque vous faites référence à des instances d'environnements de travail distants créés avec cette technologie, utilisez « codespaces » (en minuscules). Par exemple, « pour supprimer votre codespace » ou « pour lister vos codespaces ».

Utilisez toujours « conteneur Dév » (ou, si une clarification est nécessaire, sa forme développée « conteneur de développement »), et non « conteneurdév » (en un mot), sauf dans les noms de fichier/chemin. La forme en un seul mot pourrait être considérée comme une marque, ce que nous voulons éviter, et nous voulons également être cohérents avec la forme à deux mots utilisée dans la documentation Visual Studio Code.

Utilisez « fichiers de configuration de conteneur de développement » pour faire référence à tous les fichiers du répertoire .devcontainer (plus le .devcontainer.json s'il est utilisé à la place du devcontainer.json dans le répertoire .devcontainer). Ne les appelez pas « fichiers de conteneur de développement » ni « fichiers devcontainer » pour éviter que cela ne soit considéré comme faisant référence aux fichiers devcontainer.json. Les « fichiers de configuration de conteneur de développement » font référence à tous les fichiers pouvant être utilisés pour configurer un conteneur de développement, notamment les fichiers Dockerfile et compose.yaml. N'utilisez pas « le fichier de configuration de conteneur de développement » (au singulier) quand vous faites référence spécifiquement à un fichier devcontainer.json. Appelez plutôt ce fichier par son nom.

Produits GitHub Advanced Security (GHAS)

Utilisez les termes licenses et active committers lorsque vous faites référence à la facturation de GitHub Advanced Security.

Nous utilisions auparavant le terme seats pour décrire le nombre de comptes pouvant utiliser GitHub Advanced Security dans une entreprise. Les personnes peuvent être déroutées par le terme seats, aussi avons-nous supprimé ce terme de GitHub.com à l'automne 2022 et les versions à partir de GHES 3.7 ne l'utilisent plus.

Personal access tokens

GitHub a deux types de personal access tokens :

• Fine-grained personal access token : Offrent un contrôle précis sur les accès et les autorisations des dépôts
• Personal access token (classic) : Utilise des étendues et accorde l'accès à tous les référentiels auxquels le propriétaire du jeton peut accéder

Vous devez utiliser des variables pour faire référence à ces types de jeton, ainsi qu'aux personal access tokens en général :

• Utilisez {% data variables.product.pat_generic %} ou {% data variables.product.pat_generic_caps %} pour faire référence à un personal access token en général. Utilisez {% data variables.product.pat_generic_title_case %} si le terme doit commencer par une majuscule (« Personal Access Token ») afin de refléter le texte de l’interface utilisateur.
• Utilisez {% data variables.product.pat_v2 %} ou {% data variables.product.pat_v2_caps %} pour faire référence aux fine-grained personal access token.
• Utilisez {% data variables.product.pat_v1 %}, {% data variables.product.pat_v1_plural %}, {% data variables.product.pat_v1_caps %} ou {% data variables.product.pat_v1_caps_plural %} pour faire référence à un personal access token (classic).

Pour plus d’informations sur les GitHub de personal access tokens, consultez Gestion de vos jetons d’accès personnels.

Ponctuation

Suivez les règles de ponctuation de l'anglais américain standard. Pour plus d'informations, consultez « Ponctuation » dans le Guide de style Microsoft.

Notes de publication

Les notes de publication sur GitHub Docs informent les lecteurs des changements qui ont été apportés à une version d'un produit comme GitHub Enterprise Server (GHES) et qui concernent les administrateurs ou les utilisateurs. Les notes de publication se trouvent dans Notes de publication.

Une bonne note de publication se compose de quelques phrases qui répondent successivement aux questions du lecteur sur un changement. Pour plus d'informations, consultez « Type de contenu de note de publication ».

Chaque note de publication décrit l’un des changements suivants.

• Fonctionnalités : tout nouveau comportement ou toute nouvelle fonctionnalité
• Correctifs de sécurité : correction des failles ou des comportements inattendus qui ont des implications sur la sécurité
• Correctifs de bogues : correction des failles ou des comportements inattendus
• Changements : changements notables par rapport à d'anciens comportements
• Problèmes connus : Problèmes que GitHub a identifiés, mais qui ne peuvent pas être priorisés ou qui ne l'ont pas encore été
• Fermeture : processus de retrait d’une fonctionnalité qui ne doit plus être utilisée pour les travaux futurs.
• Mise hors service : fin du cycle de vie d’un produit ou d’une fonctionnalité
• Errata : correction d'une note de publication ou d'une documentation inexactes

Vous pouvez également consulter les directives relatives à la mise à jour des notes de version dans les sections Ajouter ou mettre à jour une note de version et Supprimer une note de version.

Fonctionnalités

Une note de publication relative à une fonctionnalité résume le tout nouveau comportement. Les notes relatives aux fonctionnalités ne représentent généralement qu'une partie des publications de fonctionnalités.

Rédaction de notes de publication pour les nouvelles fonctionnalités

Une note de publication relative à une fonctionnalité répond aux questions suivantes.

1. Suis-je concerné par cette nouvelle fonctionnalité, compte tenu de mon rôle ou de mon accès ?
2. À quel besoin la fonctionnalité répond-elle ?
3. En quoi consiste la fonctionnalité ?
4. Le cas échéant, où puis-je en savoir plus sur la fonctionnalité ?

          _AUDIENCE_ (**1**) PEUT _DESCRIPTION DU BESOIN_ (**2**) avec _DESCRIPTION DE L’UTILISATION DE LA FONCTIONNALITÉ_ (**3**). Pour plus d’informations, consultez [_TITRE DE L’ARTICLE_](/) (**4**)

• Catégorisez chaque fonctionnalité dans une section, sous un titre de fonctionnalité.
• Écrivez au présent.
• Pour réduire les répétitions et les mots inutiles, « maintenant » est généralement implicite.
• Pour être clair sur les acteurs et l'impact, évitez la voix passive si possible.

Exemples de notes de publication relatives à des fonctionnalités

• Les administrateurs de site peuvent renforcer la sécurité de la console de gestion en configurant la limite de débit pour les tentatives de connexion, ainsi que la durée du verrouillage après le dépassement de la limite de débit. Pour plus d’informations, consultez Configuration des limites de débit.

• Les propriétaires d'entreprise peuvent contrôler où les utilisateurs peuvent dupliquer les dépôts. La duplication peut être limitée à des combinaisons prédéfinies d’organisations, de la même organisation que le dépôt parent, des comptes d’utilisateur ou n’importe où. Pour plus d’informations, consultez Application de stratégies de gestion des référentiels dans votre entreprise.

• Les utilisateurs peuvent créer des fichiers avec des diagrammes geoJSON, topoJSON et STL et afficher les diagrammes dans l'interface web. Pour plus d’informations, consultez Travailler avec des fichiers non basés sur du code.

Correctifs de sécurité

Une note de publication relative à un correctif de sécurité résume un changement qui atténue ou empêche l'exploitation d'un problème de sécurité dans le produit. Les notes relatives aux correctifs de sécurité ne représentent généralement qu'une partie des publications de correctifs.

Rédaction de notes de publication pour les correctifs de sécurité

Une note de publication relative à un correctif de sécurité répond aux questions suivantes.

1. Si disponible, quel est l'indice de gravité NVD de la vulnérabilité corrigée ?
2. Quelle attaque peut être menée en exploitant la vulnérabilité ?
3. Quel type de vulnérabilité est exploitable ?
4. Si disponible, quel est l'identificateur CVE pour la vulnérabilité, en attente ou actif ?
5. La vulnérabilité a-t-elle été signalée via le programme GitHub Bug Bounty ?

          _GRAVITÉ_ (**1**) : Un attaquant pourrait _DESCRIPTION DE L’IMPACT_ (**2**) EN _DESCRIPTION DE L’EXPLOITATION DE LA FAILLE_ (**3**). GitHub a demandé l'ID CVE [_CVE-####-#####_](/) (**4**) de cette vulnérabilité, qui a été signalée via le [programme GitHub Bug Bounty](https://bounty.github.com) (**5**).

Exemples de notes de publication relatives aux correctifs de sécurité

•         **MOYENNE** : Un attaquant pouvait entraîner un épuisement illimité des ressources sur l'instance en effectuant des requêtes parallèles sur l'API REST Markdown. Pour atténuer ce problème, GitHub a mis à jour [CommonMarker](https://github.com/gjtorikian/commonmarker). GitHub a demandé l'ID CVE [CVE-2022-39209](https://nvd.nist.gov/vuln/detail/CVE-2022-39209) pour cette vulnérabilité.
  

•         **MOYENNE :** un attaquant pouvait incorporer des liens dangereux dans l’interface utilisateur web de l’instance, car les liens de prévisualisation des demandes de tirage n’avaient pas nettoyé correctement les URL. Cette vulnérabilité a été signalée via le [programme Bug Bounty GitHub](https://bounty.github.com).
  

Mises à jour de l'image de base et du package

Nous incluons également les mises à jour de l'image de base et du package dépendant dans la section « Correctifs de sécurité », car ces mises à jour traitent souvent des problèmes de sécurité. Nous consolidons toutes ces mises à jour dans la note suivante.

Les packages ont été mis à jour avec les dernières versions de sécurité.

Résolution des bogues

Une note de publication relative à un correctif de bogue décrit la correction d'un comportement non souhaité ou inattendu. Les notes relatives aux correctifs de bogues ne représentent généralement qu'une partie des publications de correctifs.

Rédaction de notes de publication pour les correctifs de bogues

Une note de publication relative à un correctif de bogue répond aux questions suivantes.

1. Suis-je affecté par le comportement, compte tenu de mon rôle ou de mon accès ?
2. Quel comportement le lecteur subirait-il avant la correction ?

          _AUDIENCE_ (**1**) _DESCRIPTION DU COMPORTEMENT_ (**2**).

• Étant donné que le bogue est maintenant résolu, écrivez au passé.
• Les mots comme « correction d’un bogue… » ou « correction d’un problème… » sont implicites et inutiles.
• Pour réduire les répétitions et les mots inutiles, « maintenant » est généralement implicite.
• Pour être clair sur les acteurs et l'impact, évitez la voix passive si possible.
• Si la note de version inclut un message d'erreur, formatez le message conformément aux instructions fournies dans Messages d'erreur.

Exemples de notes de publication relatives aux correctifs de bogues

• Quand un utilisateur importait un dépôt avec la protection des poussées activée, le dépôt n'était pas immédiatement visible dans la vue « Couverture de la sécurité » de la vue d'ensemble de la sécurité.

• Sur une instance avec GitHub Actions activé, un travail de workflow pour GitHub Actions ne démarrait pas si un groupe d'exécuteurs correspondant n'était pas disponible au moment de la mise en file d'attente initiale du travail, même si un groupe d'exécuteurs correspondant devenait disponible après l'entrée du travail dans la file d'attente.

• Les commandes exécutées par les administrateurs de site via SSH sur l'un des nœuds d'instance n'étaient pas journalisées dans /var/log/ssh-console-audit.log.

Changements

Une note de publication relative à un changement décrit un changement notable, mais mineur, du comportement existant. Les notes relatives aux changements répondent aux questions suivantes.

Rédaction de notes de publication pour les changements

Une note de publication relative à un changement répond aux questions suivantes.

1. Suis-je affecté par le comportement, compte tenu de mon rôle ou de mon accès ?
2. Si le changement résout ou évite un problème, quel est ce problème ?
3. Quel est le nouveau comportement ?
4. Le cas échéant, quel était le comportement avant le changement ?

          _AUDIENCE_ (**1**) / _DESCRIPTION DU PROBLÈME QUE LE CHANGEMENT RÉSOUT_ (**2**) _DESCRIPTION DU NOUVEAU COMPORTEMENT_ (**3**) _DESCRIPTION DE L'ANCIEN COMPORTEMENT_ (**4**).

• Étant donné que le changement s'applique à la version en question, rédigez les notes relatives aux changements au présent.
• Pour réduire les répétitions et les mots inutiles, « maintenant » est généralement implicite.
• Pour être clair sur les acteurs et l'impact, évitez la voix passive si possible.
• Souvent, l'audience est impliquée.
• Si c'est utile, ajoutez des liens pertinents vers GitHub Docs.

Exemples de notes de publication relatives aux changements

• Sur une instance avec une licence pour GitHub Advanced Security, les utilisateurs qui créent des modèles personnalisés pour l’analyse des secrets peuvent fournir des expressions qui doivent ou ne doivent pas correspondre et qui comportent jusqu’à 2 000 caractères. Cette limite a été augmentée de 1 000 caractères.

• Pour les administrateurs qui doivent examiner ou modifier les correspondances SAML, le chemin par défaut pour la sortie de ghe-saml-mapping-csv -d est /data/user/tmp au lieu de /tmp. Pour plus d’informations, consultez Utilitaires en ligne de commande.

• Pour éviter les problèmes intermittents liés à la réussite des opérations Git sur une instance avec plusieurs nœuds, GitHub Enterprise Server vérifie l'état du conteneur MySQL avant de tenter une requête SQL. La durée du délai d'expiration a également été réduite.

Problèmes connus

Une note de publication relative à un problème connu décrit un problème que GitHub a identifié, mais qui n'a pas encore été priorisé.

Rédaction de notes de publication pour les problèmes connus

Une note de publication relative à un problème connu répond aux questions suivantes.

1. Suis-je affecté par le comportement, compte tenu de mon rôle ou de mon accès ?
2. Quels sont les messages d'erreur, ou autres éléments d'interface utilisateur reconnaissables, qui s'affichent ?
3. Est-ce que je dois agir ? Si oui, que dois-je faire ?

          _AUDIENCE_ (**1**) _DESCRIPTION DU PROBLÈME_ (**2**) _DÉTAILS DU COMPORTEMENT_ (**3**) _ÉTAPES SUIVANTES_ (**4**).

• Pour être clair sur les acteurs et l'impact, évitez la voix passive si possible.
• Pour réduire les répétitions et les mots inutiles, « maintenant » est généralement implicite.
• Si la note de version inclut un message d'erreur, formatez le message conformément aux instructions fournies dans Messages d'erreur.
• Si c'est utile, ajoutez des liens pertinents vers GitHub Docs.
• Les problèmes connus sont également un type de contenu sur GitHub Docs. Pour plus d’informations, consultez « Type de contenu pour la résolution de problèmes ». Si cela est utile, écrivez ou créez un lien vers du contenu plus détaillé et adapté au contexte dans la documentation.

Exemples de notes de version pour les problèmes connus

• Une fois qu'un utilisateur active l'option pour un dépôt permettant aux utilisateurs avec un accès en lecture de créer des discussions, la fonctionnalité n'est pas activée.

• Lorsqu'un administrateur commence une exécution de configuration, une No such object error peut se produire pendant la phase de validation pour les services Notebook et Viewscreen. Cette erreur peut être ignorée, car les services devraient toujours démarrer correctement.

Fermeture

Une note de publication pour une fonctionnalité en cours de fermeture récapitule un comportement ou une fonctionnalité que GitHub prévoit de supprimer. Ces fonctionnalités sont toujours disponibles pour une utilisation en production et sont fournies avec les SLA de support associés et les obligations de support technique. Cependant, elles font l’objet d’un processus de mise hors service et il ne faut plus s’appuyer dessus pour les travaux futurs. La fermeture est une étape transitionnelle durant laquelle les utilisateurs sont invités à cesser d’utiliser la fonctionnalité et à se préparer à sa mise hors service.

Rédaction de notes de version concernant les fonctionnalités en cours de suppression

Une note de publication relative à une fonctionnalité en cours de fermeture répond aux questions suivantes.

1. Suis-je concerné par cette fonctionnalité existante, compte tenu de mon rôle ou de mon accès ?
2. Quelle est la fonctionnalité qui est en cours de fermeture ?
3. Le cas échéant, qu'est-ce qui remplace la fonctionnalité de fermeture ?
4. Le cas échéant, où puis-je en savoir plus ?

          _PUBLIC_ (**1**) _DESCRIPTION DE LA FONCTIONNALITÉ EN COURS DE FERMETURE_ (**2**) _FONCTIONNALITÉ DE REMPLACEMENT_ (**3**) Pour plus d’informations, consultez [_TITRE DE L’ARTICLE_](/) (**4**).

• Les notes sont au présent, ou au futur pour les changements à venir. Le cas échéant, indiquez la version à venir dans laquelle le retrait aura lieu.
• Pour réduire les répétitions et les mots inutiles, « maintenant » est généralement implicite.
• Pour être clair sur les acteurs et l'impact, évitez la voix passive si possible.
• Catégorisez chaque fonctionnalité dans une section, sous un titre de fonctionnalité.

Exemples de notes de publication relatives aux fonctionnalités en cours de fermeture

•         **Fermeture** : Dans GitHub Enterprise Server 3.8 et ultérieur, pour garantir la sécurité des instances, les algorithmes non sécurisés seront désactivés pour les connexions SSH à l'interpréteur de commandes d'administration.
  

• Les commentaires de commit, qui sont des commentaires que les utilisateurs ajoutent directement à une validation en dehors d'une pull request, n'apparaissent plus dans l'historique des pull requests. Les utilisateurs ne pouvaient pas répondre à ces commentaires ni les résoudre. L'API REST des événements de chronologie et l'objet PullRequest de l'API GraphQL ne retournent plus de commentaires de commit.

Mis hors service

Les produits ou fonctionnalités mis hors service ne sont plus disponibles pour les nouveaux clients, commercialisés, pris en charge ni documentés. À ce stade, le produit est effectivement rendu indisponible et aucun nouveau développement ni correctif ne sera fourni. La seule prise en charge des produits supprimés peut découler d’engagements existants, tels que ceux requis pour les versions précédemment publiées de GitHub Enterprise Server. La mise hors service marque la fin officielle du cycle de vie d’un produit ou d’une fonctionnalité, sans mise à jour, correctif de bogue ni support utilisateur supplémentaire, signalant une transition complète vers des outils ou services plus récents.

Rédaction de notes de publication pour les fonctionnalités mises hors service

Une note de publication relative à une fonctionnalité mise hors service répond aux questions suivantes.

1. Suis-je concerné par cette fonctionnalité, compte tenu de mon rôle ou de mon accès ?
2. Quelle est la fonctionnalité mise hors service ?
3. Le cas échéant, qu'est-ce qui remplace la fonctionnalité mise hors service ?
4. Le cas échéant, où puis-je en savoir plus ?

          _PUBLIC_ (**1**) _DESCRIPTION DE LA FONCTIONNALITÉ EN COURS DE RETRAIT_ (**2**) _FONCTIONNALITÉ DE REMPLACEMENT_ (**3**) Pour plus d’informations, consultez [_TITRE DE L’ARTICLE_](/) (**4**)

• Les notes sont rédigées au présent.
• Pour réduire les répétitions et les mots inutiles, « maintenant » est généralement implicite.
• Pour être clair sur les acteurs et l'impact, évitez la voix passive si possible.
• Catégorisez chaque fonctionnalité dans une section, sous un titre de fonctionnalité.

Exemples de notes de publication relatives à des fonctionnalités mises hors service

•         **Supprimé** : GitHub ne prend plus en charge les workflow requis pour les GitHub Actions dans GitHub Enterprise Server 3.11 et versions ultérieures. Utilisez plutôt des ensembles de règles de dépôt. Pour plus d'informations, consultez « [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging) ».
  

Errata

Un errata corrige les informations inexactes précédemment publiées dans les notes de publication ou la documentation d'une version.

Rédaction d'un errata

L'errata répond aux questions suivantes.

1. Le cas échéant, quelle section des notes de publication ou du contenu sur GitHub Docs est affectée ?
2. Les informations incorrectes s'appliquent-elles à moi, compte tenu de mon rôle ou de mon accès ?
3. Qu'est-ce que la note de publication ou la documentation a décrit qui était incorrect ?
4. Quand l'errata a-t-il été publié ?

          _CONTENU_ (**1**) a indiqué à tort que _AUDIENCE_ (**2**) peut _RÉSUMÉ DES INFORMATIONS INEXACTES_ (**3**). [Mise à jour : _DATE DE PUBLICATION_**4**]

• Mettez en forme la date de publication en respectant les instructions dans Ajout ou mise à jour d'une note de publication.

Exemple d'errata

•         [Les fonctionnalités](/) indiquaient par erreur que les utilisateurs de la GitHub Advisory Database peuvent voir des avis pour Elixir, le gestionnaire de paquets Hex d'Erlang, et bien d'autres choses encore. Cette fonctionnalité n'est pas disponible dans GitHub Enterprise Server 3.7 et sera disponible dans une version future. [Mise à jour : 01/06/2023]
  

Ajout ou mise à jour d'une note de publication

Pour signaler aux lecteurs que vous avez ajouté ou modifié une note, ou pour indiquer la date de publication de l'errata, ajoutez un horodatage au format « [Mise à jour : JJ-MM-AAAA] ».

Suppression d’une note de publication

Pour signaler que nous avons supprimé une note de publication, ajoutez une section « Errata » détaillant la note que vous avez supprimée et (le cas échéant) la version à laquelle la note supprimée se rapporte réellement. Consultez Rédaction d’errata.

Libérer les références

Lorsque vous faites référence à une série de versions à partir d’une version particulière, utilisez « ou version ultérieure ».

• À utiliser : « version 0.41.0 ou ultérieure »
• À éviter : « version 0.41.0 ou supérieure »
• À éviter : « version 0.41.0 ou plus »

Éléments réutilisables et variables

Utilisez des chaînes réutilisables pour des noms individuels (par exemple, des noms de produit) ou pour des phrases ou des paragraphes complets. Bouts de phrases et expressions ne doivent pas être contenus dans des chaînes réutilisables, car ils peuvent causer des problèmes lorsque le contenu est traduit. Pour plus d’informations, consultez le répertoire de données dans le référentiel github/docs, Création de contenu réutilisable et la section Noms de produit de ce document.

Tables des matières sectionnelles

Si une section d'un article utilise des titres de type H3 ou H4 pour diviser davantage le contenu et que seule une partie du contenu intéresse le lecteur, vous pouvez utiliser une table des matières locale pour l'aider à identifier et à accéder aux informations qui l'intéressent le plus. Par exemple, dans Streaming de journaux d’audit pour votre entreprise, les utilisateurs ne configureront probablement la diffusion en continu des journaux d’audit que pour un seul fournisseur. Par conséquent, la table des matières de la section « Configuration de la diffusion en continu des journaux d’audit » permet aux utilisateurs de sélectionner leur fournisseur et d’accéder au contenu pertinent sans avoir à lire l’intégralité de la section.

N'ajoutez pas de table des matières locale si les titres de section H3 ou H4 sont utilisés uniquement pour regrouper du contenu et si toutes les informations peuvent intéresser le lecteur. Par exemple, dans Notions de base de la gestion des identités et des accès, les utilisateurs doivent lire et prendre en compte chaque section car elles parlent toutes de leur entreprise. Nous n'incluons pas de table des matières locale dans cet article parce que les utilisateurs doivent lire chaque section, et non choisir l'une d'entre d'elles. L'ajout d'une table des matières locale obligerait également les personnes qui utilisent des lecteurs d'écran ou d'autres technologies adaptatives à appuyer sur TAB et à parcourir d'autres titres de section avant de trouver ce dont elles ont besoin.

Présentez les tables des matières sectionnelles sous forme de liste. Incluez toutes les sous-sections dans l'ordre dans lequel elles apparaissent dans l'article et faites-y référence avec le titre de section complet.

Les tables des matières locales doivent être introduites avec une phrase ou un paragraphe qui aide les lecteurs à comprendre comment le contenu est organisé et à sélectionner la section qui les intéresse le plus. N'incluez pas de table des matières locale directement sous un titre de section.

Exemples de tables de matières sectionnelles

## Setting up the application

Set up your application according to your operating system.

* [Setting up for macOS](#setting-up-for-macOS)
* [Setting up for Windows](#setting-up-for-windows)
* [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

* [Windows 98](#windows-98)
* [Windows Vista](#windows-vista)
* [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

Tables

Les tables sont ajoutées à GitHub Docs à l'aide de Markdown. Comme les tables peuvent être difficiles à lire et à gérer, assurez-vous avant de créer une table que la représentation sous forme de tableau, au lieu d'un autre format comme une liste, est la plus adaptée aux données de la table. Chaque ligne d’un tableau doit commencer et se terminer par une barre verticale, |.

Utiliser des tableaux uniquement pour présenter des informations tabulaires

Les tableaux fonctionnent mieux pour présenter des données tabulaires, telles que des informations à comparer ou des valeurs avec plusieurs attributs. N’utilisez pas de tableaux pour les listes simples. Consultez la section Listes de ce document.

Éviter de décrire les données de tableau

Les données d'un tableau et la raison pour laquelle elles sont importantes doivent être claires par rapport au contenu précédent, les en-têtes de colonne et (si nécessaire) les en-têtes de ligne. Évitez les descriptions inutiles des données d'un tableau. Si les données d'un tableau ne sont pas claires sans une description longue, déterminez si votre tableau a besoin d'en-têtes de ligne ou si les informations seraient mieux communiquées d'une autre manière.

Par exemple, dans Documentation de référence relative aux runners auto-hébergés, un tableau comparant les fonctionnalités entre deux solutions de mise à l’échelle automatique prises en charge est introduit avec la phrase Each solution has certain specifics that may be important to consider. L’article ne décrit aucune des différentes fonctionnalités comparées, car ces informations sont clairement communiquées dans le tableau.

• Utiliser : « Différentes limites de taille par dépôt s'appliquent en fonction de votre version de GHES. »
• Éviter : « La première ligne du tableau présente l'information concernant GitHub Enterprise Cloud. La deuxième ligne montre les informations relatives à GitHub Enterprise Server. »
• Éviter : « Le tableau ci-dessous montre le type de données de migration exportées. »

Utiliser le balisage approprié pour les en-têtes de ligne et de colonne

Les tableaux dans lesquels la première colonne décrit les valeurs de données du tableau (mais ne sont pas les données elles-mêmes) doivent être balisés avec des en-têtes de ligne. C'est important pour la technologie d'assistance de comprendre les relations entre les cellules.

Par exemple, dans le tableau suivant, pour donner un sens aux valeurs « Oui » et « Non » du tableau, vous devez connaître à la fois l'en-tête de colonne (rôle) et l'en-tête de ligne (autorisation).

Pour ajouter des en-têtes de ligne dans un tableau Markdown, enveloppez le tableau entre les balises Liquid {% rowheaders %} {% endrowheaders %}. Pour plus d'informations sur l'utilisation des en-têtes de ligne, voir Utilisation de Markdown et Liquid dans GitHub Docs.

Inclure une valeur pour chaque cellule

Chaque cellule d'un tableau doit contenir une valeur.

Pour les cellules sans données, utilisez « Aucun » ou « Non applicable ». N'utilisez pas « NA » ou « N/A ».

Pour les tableaux comportant des en-têtes de ligne, la première cellule (cellule « A1 ») doit décrire les en-têtes de ligne afin d'aider les utilisateurs à comprendre l'ensemble du tableau. Toutefois, si cela risque de rendre le tableau moins clair ou d'ajouter des informations redondantes, vous pouvez laisser cette cellule vide. Par exemple, dans l'article Génération et test de code PowerShell, la première cellule peut être étiquetée comme « Modules », mais étant donné que chaque en-tête de ligne inclut déjà le mot « module », cet en-tête répète les informations qui n'ajoutent pas de valeur descriptive à la compréhension du tableau dans son ensemble.

Utiliser des symboles et des intitulés clairs et cohérents

Pour les tableaux qui utilisent des symboles :

• Remplissez toutes les cellules. Par exemple, dans un tableau d'autorisations, ne marquez pas uniquement les cellules pour les éléments qui nécessitent une autorisation.
• Utilisez des octicons ou le format SVG. N'utilisez pas d'emoji. Pour plus d'informations sur les octicons, consultez Utilisation de Markdown et Liquid dans GitHub Docs.
• Utilisez une coche pour les valeurs affirmatives (« Oui », « Obligatoire », « Pris en charge ») et une croix pour les valeurs négatives (« Non », « Facultatif », « Non pris en charge »).
• Utilisez aria-label pour décrire la signification du symbole, et non son aspect visuel. Par exemple, « Obligatoire », et non « Icône de coche ».

Lorsque les données de tableau ne sont pas vraiment binaires (chaque valeur est « Oui » ou « Non », par exemple), des valeurs de texte peuvent être nécessaires en plus des symboles ou à la place des symboles. Par exemple, dans la page À propos du support GitHub, certaines fonctionnalités sont marquées comme « Disponibles à la vente ».

Utiliser les notes de bas de page avec parcimonie

Consultez Notes de bas de page.

Aligner le contenu du tableau avec cohérence

Toutes les colonnes d'un tableau doivent être alignées à gauche, à l'exception des colonnes contenant uniquement des octicons qui doivent être centrées. Si une colonne contient à la fois du texte et des octicons, utilisez le centrage.

Le contenu du tableau est aligné à gauche par défaut. Utilisez la mise en forme de tableau Markdown, deux points (:) à droite ou à gauche des tirets dans la ligne d’en-tête, pour spécifier l’alignement de chaque colonne. Pour plus d’informations, consultez Organisation des informations avec des tables.

L’exemple suivant montre une partie d’un tableau qui se trouve dans Référence des options Dependabot.

La table est générée avec la syntaxe d'alignement suivante.

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

Titres

Utilisez la casse de phrase pour les titres.

Titres courts

Nous utilisons des titres courts pour renseigner la barre latérale de navigation. Étant donné que les titres courts apparaissent dans la barre latérale de navigation, ils peuvent utiliser le contexte pour transmettre la signification et être légèrement moins précis que les titres complets. L'objectif des titres courts est d'aider les personnes à trouver le contenu qu'ils recherchent sans avoir d'éléments trop longs dans la barre latérale de navigation. Les titres courts donnent aux personnes une compréhension contextuelle d'un article et s'alignent sur les normes suivantes.

• Les titres courts comportent 2 à 3 mots.
  • Pour les catégories, les titres courts doivent comporter moins de 27 caractères.
  • Pour les sujets de cartes, les titres courts doivent comporter moins de 30 caractères.
  • Pour les articles, les titres courts doivent comporter moins de 31 caractères, idéalement entre 20 et 25 caractères.
• Les titres courts utilisent la forme de base des verbes plutôt que des gérondifs. * Utilisez : « Configurer les notifications » plutôt que « Configuration des notifications ».
• Les titres courts pour les catégories, les thématiques et les articles peuvent omettre les noms de produits et de fonctionnalités s'il est évident à quel produit ou à quelle fonctionnalité ils se réfèrent. * Utilisez : « Configurer les notifications » comme titre court pour Configuration de notifications pour les alertes Dependabot, car l'article se trouve dans la rubrique de mappage « Dependabot alerts ».
• N'introduisez pas de nouveaux mots dans les titres courts qui ne figurent pas dans le titre complet.
• Les titres courts doivent être semblables aux titres complets pour avoir un contenu similaire. * Utilisez : « Organisations et équipes » et « Comptes d'entreprise » * Évitez : « Organisations et équipes » et « Gestion des comptes d'entreprise »

L'écriture de titres courts peut être difficile. Pour obtenir plus facilement des titres courts respectant la limite de caractères, pensez au titre court dans son contexte. Supprimez si possible les mots répétés et les noms de produits ou de fonctionnalités figurant dans la thématique ou la catégorie à laquelle appartient le contenu.

Contenu d'une politique de site

N'utilisez pas d'éléments réutilisables ou de variables dans le contenu d'une politique de site. Ces articles sont des documents juridiques et doivent avoir une source lisible par un humain.

Le contenu d'une politique de site utilise le même style et les mêmes modèles que le reste de GitHub Docs.

Éléments de l'interface utilisateur

Gras

Pour décrire les éléments d'interface utilisateur avec lesquels interagir, mettez-les en gras.

• Dans la barre latérale à gauche, cliquez sur Facturation.
• Regardez dans la boîte de fusion en bas de l'onglet Conversation de la pull request.
• À côté de Titre, ajoutez un nom descriptif pour votre nouvelle clé.

Noms de branche

Utilisez la mise en forme du code pour les noms de branche.

• main
• USERNAME.github.io

Boutons

Mettez les noms de bouton en gras et, dans la mesure du possible, omettez le mot « bouton ». Pour décrire l'utilisation d'un bouton, écrivez « cliquer », et non « presser » ou « appuyer ».

• Utilisation : Cliquez sur Pull request.
• Éviter : Appuyez sur le bouton Demande de tirage.

Cases à cocher

Mettez les noms de case à cocher en gras et omettez le mot « case à cocher ». Pour décrire qu'une case doit être cochée ou décochée, utilisez « sélectionner » ou « désélectionner ».

• Utiliser : Sélectionnez Activer pour tous les nouveaux dépôts.
• Éviter : Cochez la case « Activer pour tous les nouveaux référentiels ».

Texte dynamique

Utilisez des lettres majuscules pour indiquer le texte qui change dans l'interface utilisateur ou que l'utilisateur doit fournir dans une commande ou un extrait de code.

• Utilisation : Cliquez sur Ajouter NOM D'UTILISATEUR à NOM DE DÉPÔT.

Listes et éléments de liste

Mettez en gras les listes et les éléments de liste sur lesquels l'utilisateur peut cliquer. Pour décrire une interaction avec une liste, comme un menu déroulant ou un élément d'interface utilisateur qui se développe, que le nom de la liste soit un mot ou un octicon, écrivez « sélectionner ». Pour décrire le choix d'un élément de liste, écrivez « cliquer ».

• Utiliser : Sélectionnez le menu déroulant Sauvegarder les adresses e-mail, puis cliquez sur Autoriser uniquement l'adresse e-mail principale.
• Éviter : Cliquez sur le menu déroulant « Sauvegarder les adresses e-mail », puis sur Autoriser uniquement l'adresse e-mail principale.

Emplacement

Conformément aux recommandations WCAG, nous devons décrire les éléments par leur nom et non uniquement par leur apparence ou leur emplacement. Le Guide de style Microsoft fournit des recommandations spécifiques pour les expressions directionnelles, en mettant l’accent sur leur utilisation dans la documentation.

• Au-dessus ou en dessous
• En haut à gauche, en haut à droite
• En bas à gauche, en bas à droite
• À côté de la page, en bas ou en haut, à gauche ou à droite

Panneaux

Lorsque cela est possible, évitez de faire référence à des panneaux. Décrivez plutôt ce que l'utilisateur doit faire.

• Utiliser : Cliquez sur Afficher les graphiques et les graphes de votre dépôt, puis sélectionnez la période que vous souhaitez voir dans le menu déroulant.
• Éviter : Cliquez sur Afficher les graphiques et les graphes pour ouvrir le panneau du dépôt sélectionné, puis sélectionnez la période que vous souhaitez voir dans le menu déroulant.

Si vous devez faire référence à un panneau pour décrire un changement de l'interface utilisateur ou expliquer comment interagir avec l'interface utilisateur, mettez en forme le nom du panneau comme du texte d'interface utilisateur. Incluez le mot « panneau » seulement si celui-ci apporte de la clarté ou si le panneau n'a pas de nom dans l'interface utilisateur.

• Utiliser : Dans le panneau « Couverture de la sécurité », sélectionnez Activer ou Désactiver.
• Utiliser : Dans le panneau, sélectionnez Activer ou Désactiver.

Cases d'option

Mettez en gras les noms des boutons radio et omettez les mots « boutons radio » ou tout autre élément descriptif. Pour décrire l’utilisation d’une case d’option, écrivez « sélectionner ».

Noms de dépôt

Utilisez une police de caractères monospaciale avec des guillemets inversés pour les noms des référentiels. Fournissez un lien vers les référentiels lorsque les utilisateurs sont censés y accéder.

• Utilisation : consultez le référentiel github/docspour plus d’informations.

Éléments adaptatifs

Nous documentons uniquement les états adaptatifs des éléments d'interface utilisateur lorsqu'ils créent une ambiguïté ou une confusion. Si une tâche n'est pas claire en raison d'un élément d'interface utilisateur adaptatifs, décrivez l'interaction que quelqu'un doit faire pour atteindre l'objectif de la tâche. Ne vous limitez pas à la description de l'état visuel de l'élément d'interface utilisateur.

• Utilisez : Cliquez sur Sécurité. Si Securité n’est pas visible, cliquez sur ⋮ pour développer le menu du référentiel.

Texte de l'interface utilisateur

Lorsque vous faites référence à du texte dans l'interface utilisateur, reproduisez le texte à l'identique. Utilisez des chevrons pour entourer le texte de l'interface utilisateur avec lequel il n'est pas possible d'interagir. Placez les virgules en dehors des guillemets.

• Utiliser : Sous « Liste d'adresses IP autorisées », cliquez sur Modifier.

Plus de ressources

Guide de style de Microsoft :

• Mise en forme du texte dans les instructions

Vidéos

Vous pouvez ajouter des vidéos pour renforcer le texte, mais les vidéos ne doivent jamais remplacer le contenu écrit. Les vidéos ne sont pas accessibles à certains utilisateurs et sont également difficiles à trouver en effectuant une recherche.

Les vidéos sur le site web GitHub Docs doivent être bien produites, contenir moins d'obstacles pour les personnes atteintes d'un handicap et être conformes à notre modèle de contenu relatif aux vidéos. Pour plus d’informations, consultez À propos de l’utilisation de vidéos dans GitHub Docs.

Voix et ton

Utilisez un langage clair et simple, accessible à un large éventail de lecteurs. Soyez authentique, empathique et sûr de vous dans ce que vous écrivez.

Écrivez pour votre audience : du jargon et des termes techniques sont nécessaires, mais ne partez pas du principe que tous les lecteurs ont le même niveau d'expertise technique.

Utilisez la voix active dans la mesure du possible. Les voix passives sont acceptables lorsque vous devez mettre l'accent sur l'objet d'une action.

Nous sommes une communauté mondiale de développeurs. Évitez les tournures de phrase, les expressions idiomatiques et l'argot qui sont propres à une région ou à un pays.

Pour en savoir plus sur l'écriture de contenu accessible, consultez « La voix de la marque Microsoft : Avant tout, simple et humaine » et « Les 10 meilleurs conseils pour le style et la voix de Microsoft ».

Choix des mots et terminologie

Pour obtenir des conseils d’ordre général et des termes spécifiques à GitHub, consultez notre Glossaire. Pour obtenir des conseils plus détaillés, consultez la « liste des termes de A-Z » dans le guide de style de Microsoft.

Abréviations

Utilisez les mots entiers, sauf lorsque vous faites référence à un mot qui est explicitement abrégé dans le produit lui-même.

• Utiliser : Dépôt
• Éviter : Réf
• Utiliser : Administrateur, personnes avec des autorisations admin
• Éviter : Administrateurs

N'utilisez pas de symboles ou d'octicons qui ne sont pas utilisés dans l'interface utilisateur de GitHub.

• Utiliser : Cliquez sur Fichier, puis sur Modifier.
• Éviter : Cliquez sur Fichier > Modifier.

Comptes

Noms de produit et comptes

Pour éviter toute ambiguïté et toute confusion, n'utilisez pas de noms de produit comme adjectifs pour décrire des comptes dans l'un de nos produits. Au lieu de cela, clarifiez le type de compte et choisissez une formulation plus claire qui évite de confondre les comptes et les produits. Lorsque vous parlez de comptes, faites uniquement référence au nom du produit si vous avez besoin de lever toute ambiguïté entre les produits. Pour plus d’informations sur les types de compte disponibles dans les produits GitHub, consultez Types de comptes GitHub.

• Utiliser : Votre organisation sur GitHub Enterprise Cloud
• Éviter : Votre compte GitHub Enterprise Cloud
• Éviter : Votre organisation GitHub Enterprise Server
• Utiliser : Vous pouvez mettre en valeur votre travail sur GitHub Enterprise Server en envoyant le nombre de contributions sur votre profil GitHub.com.

Comptes de personnes individuelles sur GitHub

Nous faisons référence à un compte auquel une personne individuelle se connecte de différentes manières en fonction du contexte.

À moins que le contenu ne concerne l'administration d'un produit d'entreprise, décrivez le compte d'une personne individuelle sur GitHub comme un « compte personnel ». Cela crée une cohérence avec l'interface utilisateur et empêche les lecteurs d'être perturbés en voyant deux termes qui signifient la même chose.

• Utiliser : Gestion des rappels planifiés pour votre compte personnel
• Éviter : Gestion des rappels planifiés pour votre compte d'utilisateur

Comptes pour les produits d'entreprise

Avec les produits d'entreprise de GitHub, les administrateurs gèrent un compte d'entreprise. Un compte d'entreprise peut avoir plusieurs organisations, et les comptes d'utilisateur des personnes peuvent être membres des organisations. Pour plus d'informations, consultez l'article « Rôles dans une entreprise » pour chaque produit.

• GitHub Enterprise Cloud
• GitHub Enterprise Server

Si le lecteur gère un compte d'entreprise et que vous décrivez les comptes des personnes qu'il gère, utilisez « compte d'utilisateur ». Cela s'applique aux produits suivants.

• GitHub Enterprise Cloud avec Enterprise Managed Users * Utiliser : Avec Enterprise Managed Users, vous pouvez créer et gérer des comptes d’utilisateur pour vos membres d’entreprise. * Éviter : Avec Enterprise Managed Users, vous pouvez créer et gérer des comptes personnels pour vos membres d’entreprise.
• GitHub Enterprise Server * Utiliser : Si vous avez besoin de prendre temporairement le contrôle d’un compte d’utilisateur… * Éviter : Si vous avez besoin de prendre temporairement le contrôle d’un compte personnel…

La documentation suivante doit faire référence aux « comptes d'utilisateur ».

• Le produit Documentation pour les administrateurs d’entreprise
• Documentation de facturation spécifique à l’entreprise, comme Facturation pour GitHub Entreprise
• Contenu dans d’autres produits qui est destiné à des administrateurs, comme Bonnes pratiques pour sécuriser les comptes dans le produit « Codage sécurisé » ou Configuration d’une version d’évaluation de GitHub Enterprise Cloud dans le produit « Démarrer »
• Contenu de l’API spécifique à l’entreprise, comme la documentation de référence sur l’API REST Endpoints d’API REST pour l’administration de GitHub Enterprise

Pour les entreprises sur GitHub Enterprise Cloud qui n'utilisent pas Enterprise Managed Users, utilisez « compte personnel » pour décrire les membres des organisations appartenant à l'entreprise.

• Utiliser : Si vous configurez l'authentification unique SAML, les membres de votre organisation continueront de se connecter à leurs comptes personnels sur GitHub.com.
• Éviter : Si vous configurez l'authentification unique SAML, les membres de votre organisation continueront de se connecter à leurs comptes d'utilisateur sur GitHub.com.

La documentation qui décrit GitHub Enterprise Cloud sans Enterprise Managed Users se trouve généralement dans la catégorie Gestion de l’authentification unique SAML pour votre organisation.

Comptes d'utilisateurs pour d'autres services

Lorsque vous décrivez le compte d'une personne pour un service autre que GitHub, tel qu'un fournisseur d'intégration ou d'authentification, utilisez « compte d'utilisateur ».

Acronymes

Développez les acronymes la première fois qu’ils sont utilisés dans un article, sauf dans les titres ou titres de section.

Applications

Utilisez « app » ou « application » dans le contenu général.

• Utiliser : Publier et référencer votre application dans GitHub Marketplace

Utilisez « application » lorsque vous faites référence à OAuth apps, car il ne s'agit pas d'un produit.

• Utiliser : Inscrire une OAuth app
• Éviter : Enregistrer une application OAuth

Utilisez « Application » lorsque vous faites référence à GitHub Apps, car il s'agit d'un produit.

• Utilisation : Enregistrer une GitHub App

GitHub Apps et OAuth apps se composent de deux parties : l'inscription de l'application et le code qui permet à l'application de faire quelque chose.

• Pour faire simplement référence aux paramètres/à la configuration de GitHub App dans l’interface utilisateur de GitHub, utilisez la terminologie telle que « inscrire » et « inscription de GitHub App ». * Utilisation : Enregistrer une GitHub App * Utiliser : Mettre à jour une inscription d'GitHub App * Éviter : Créer une GitHub App * Éviter : Modifier une GitHub App

• Pour faire simplement référence au code de l'application, utilisez une terminologie comme « code pour votre application » ou « code de votre application ». * Utiliser : code pour votre application * Utiliser : code pour votre GitHub App * Utiliser : code de votre application * Éviter : Votre GitHub App * Éviter : Votre OAuth app

• Pour faire référence à l'ensemble de l'application comme un tout (inscription + code), utilisez GitHub App ou OAuth app.

Les GitHub Apps peuvent être installées sur des comptes d'organisation et d'utilisateur. Pour faire référence à une installation de l'application, utilisez « installation de l'GitHub App » au lieu de « GitHub App ».

Monnaie

Lorsque vous faites référence à des dollars, des cents ou des montants, ou que vous utilisez le signe $, assurez-vous que la monnaie utilisée est définie même si le montant est égal à zéro. Utilisez le nom de la monnaie selon la norme ISO et le code monétaire selon la norme ISO si possible.

Utilisez des minuscules pour les noms des monnaies, mais mettez en majuscules la référence au pays ou à la région.

• Utilisez : dollar US.
• Éviter : Dollar US, dollar $USD.

Utilisez des majuscules pour les codes monétaires.

• Utiliser : USD.

Lorsqu'il n'y a qu'une seule référence dans un article, utilisez le nom de la monnaie sans le signe $ précédant le montant.

• Utiliser :10 US dollars pour une seule référence à une monnaie.

Lorsqu'un article contient plusieurs références à la même monnaie, vérifiez que la première référence utilise le nom de la monnaie sans signe $ précédant le montant et inclut le code monétaire entre parenthèses après le nom de la monnaie.

Pour les références suivantes dans un article ou le cas échéant (par exemple, lorsque l'espace est à prendre en considération, ou lorsque plusieurs montants sont présentés dans un tableau ou une liste), incluez le signe $ précédant le montant et utilisez le code monétaire de la norme ISO après le montant.

• Utiliser :10 US dollars (USD) pour la première référence et $0.25 USD pour les références suivantes.
• Éviter :$10 US dollars (USD), USD$0.25.

Lorsque la première référence concerne des centimes ou un montant autre qu’en dollar, mettez en majuscules la référence au pays ou à la région de la monnaie utilisée entre parenthèses immédiatement après la première référence. Les références monétaires suivantes sont traitées conformément aux instructions ci-dessus.

• Utiliser :99 cents (US currency) pour la première référence et 99 cents pour les références suivantes.
• Éviter :$0.99 (US currency), $0.99 USD cents, USD$0.99 cents.

Autorisations

Une autorisation est la possibilité d'effectuer une action spécifique. Par exemple, la possibilité de supprimer un problème est une autorisation.

Un rôle est un jeu d'autorisations qui peuvent être attribuées à un utilisateur. Les rôles existent à différents niveaux.

• Comptes (par exemple, propriétaire d'organisation, gestionnaire de facturation pour un compte d'entreprise)
• Ressources (par exemple, écrire dans un référentiel, administration d'un avis de sécurité)
• Équipes (par exemple, « Responsable d’équipe »)

L'accès d'une personne fait généralement référence à toutes les capacités dont elle dispose dans un contexte particulier, quels que soient les rôles ou les autorisations individuelles d'où elle tire ces capacités.

Utilisez uniquement autorisation ou rôle lorsque la distinction entre les deux est importante. Sinon, utilisez accès.

• Utiliser : Pour créer un rôle de référentiel personnalisé, vous choisissez un rôle hérité, puis ajoutez des autorisations individuelles.
• Utiliser : Gérer l’accès d’une équipe au dépôt de votre organisation
• Utiliser : Si l’appartenance à votre équipe vous donne un niveau d’accès différent de celui de votre rôle comme propriétaire d’organisation…
• Utiliser : Les personnes avec un accès en écriture peuvent…
• Éviter : les personnes disposant du rôle d’écriture peuvent…
• Éviter : les personnes disposant d’un rôle d’écriture peuvent…
• Éviter : Les personnes avec des autorisations d'écriture peuvent…
• Éviter : les personnes disposant de privilèges d’écriture peuvent…

Lorsque vous spécifiez l'accès requis pour effectuer une action, 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, qui est un 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 celui qui régit réellement votre capacité à effectuer l'action. Il s'agit donc du seul rôle devant être mentionné.

• Utiliser : les personnes disposant d’un accès en écriture à un référentiel peuvent effectuer X sur le référentiel.
• Éviter : les propriétaires de l’organisation et les personnes disposant d’un accès en écriture peuvent effectuer X sur le référentiel.

Pour plus d'informations sur le choix des mots pour les instructions d'autorisation, consultez Contenu d’un article GitHub Docs dans le modèle de contenu.

Prépositions

Évitez de terminer une phrase par une préposition, sauf si la réécriture de la phrase semble maladroite ou trop formelle.

Noms de produits

Consultez la section « Noms de produit » de ce guide.

Termes à utiliser ou à éviter

Choix des mots

Verbes ambigus

Lorsqu'une tâche est requise ou qu'une option est préférée à une autre, évitez d'utiliser des verbes auxiliaires modaux ambigus tels que « peut », « pourrait », « devrait », et « serait ». Ces verbes peuvent être interprétés comme une commande ou une suggestion. Utilisez plutôt des verbes qui indiquent clairement si l'action est requise ou facultative. Si quelque chose est facultatif ou une suggestion, vous pouvez utiliser ces verbes à condition d'indiquer clairement que l'action est facultative.

• Utiliser : vous pouvez choisir les raccourcis clavier à utiliser.
• Utiliser : utilisez la commandes git clone pour cloner un référentiel
• Éviter : vous pouvez utiliser la commande git clone pour cloner un référentiel
• Éviter : Vous pouvez supprimer la branche.

Pluriels invisibles

Évitez les pluriels invisibles, qui sont des mots ayant une signification ambiguë, car ils peuvent être interprétés comme singuliers ou pluriels. Par exemple, « récupération de fichiers » peut faire référence à la récupération d'un seul fichier ou de plusieurs fichiers.

• Utiliser : une fois le fichier récupéré, sélectionnez où l'enregistrer.
• Éviter : après la récupération de fichier, sélectionnez où l'enregistrer.

Nominalisations

Évitez les nominalisations, qui sont des noms créés à partir de verbes ou d'adjectifs. Les nominalisations peuvent rendre les phrases plus longues, plus difficiles à comprendre et à traduire.

• Utiliser : une fois le workflow terminé, le package est visible.
• Éviter : après la fin du workflow, le package sera visible.

Enchaînements de noms

Évitez les modificateurs empilés (successions de noms), qui peuvent entraîner des traductions incorrectes, car les traductions risquent de ne pas être en mesure de dire quel mot modifie l'autre. Vous pouvez reformuler la succession de noms à l'aide d'une préposition. Si l'utilisation d'un modificateur empilé est indispensable, assurez-vous que les informations autour et le contexte sont clairs afin que les lecteurs et le traducteur puissent comprendre ce qui est modifié.

• Utiliser : Paramètres source par défaut pour les dépôts publics
• Éviter : Paramètres par défaut de la source dans un dépôt public

Noms et les pronoms vagues

Si un pronom semble faire référence à plusieurs antécédents, reformulez la phrase pour clarifier l'antécédent, ou remplacez le pronom par un nom pour éliminer toute ambiguïté.

• Utiliser : après avoir effectué votre dernier commit sur votre branche et fusionné votre pull request, vous pouvez supprimer votre branche.
• Éviter : après avoir effectué votre dernier commit sur votre branche et fusionné votre pull request, vous pouvez la supprimer.