Grammaire et style

La documentation Docker doit toujours être rédigée en anglais américain avec la grammaire américaine.

Acronymes et initialismes

Un acronyme est une abréviation que vous prononceriez comme un mot, par exemple, ROM (pour read only memory). D'autres exemples incluent radar et scuba, qui ont commencé comme des acronymes mais sont maintenant considérés comme des mots à part entière.

Un initialisme est un type d'acronyme qui comprend un groupe de lettres initiales utilisées comme abréviation pour un nom ou une expression. Si vous utilisiez l'acronyme dans une conversation orale, vous énonceriez chaque lettre : H-T-M-L pour Hypertext Markup Language.

Meilleure pratique

• Épelez les acronymes ou initialismes moins connus lors de leur première utilisation, puis faites suivre de l'acronyme ou de l'initialisme entre parenthèses. Ensuite, tout au long du reste de votre page ou document, utilisez l'acronyme ou l'initialisme seul.

‘Vous pouvez utiliser l'authentification unique (SSO) pour vous connecter à Notion. Vous devrez peut-être demander à votre administrateur d'activer le SSO.’

• Lorsque l'acronyme ou l'initialisme est plus couramment utilisé que l'expression complète, par exemple, URL, HTML, vous n'avez pas besoin de suivre cette règle d'épellation.
• Utilisez des majuscules pour les acronymes de types de fichiers (un fichier JPEG).
• N'utilisez pas d'apostrophes pour les acronymes au pluriel. ✅URLs ❌URL'S
• Évitez d'utiliser un acronyme pour la première fois dans un titre ou un en-tête. Si la première utilisation de l'acronyme se trouve dans un titre ou un en-tête, introduisez l'acronyme (entre parenthèses, après le terme épelé) dans le premier corps de texte qui suit.

Gras et italique

Sauf si vous vous référez à du texte d'interface utilisateur ou à du texte défini par l'utilisateur, vous ne devriez pas ajouter d'emphase au texte. Une formulation claire et chargée à l'avant rend le sujet d'une phrase clair.

Meilleure pratique

• N'utilisez pas le gras pour vous référer au nom d'une fonctionnalité.
• Utilisez l'italique avec parcimonie, car ce type de formatage peut être difficile à lire dans les expériences numériques. Les exceptions notables sont les titres d'articles, de billets de blog ou de documents de spécification.

Majuscules

Utilisez la casse de phrase pour presque tout. La casse de phrase signifie ne mettre en majuscule que le premier mot, comme vous le feriez dans une phrase standard.

Les éléments de contenu suivants doivent utiliser la casse de phrase :

• Titres de webinaires et d'événements
• En-têtes et sous-en-têtes dans tous les types de contenu
• Appels à l'action
• En-têtes dans les boîtes de texte
• En-têtes de colonne et de ligne dans les tableaux
• Liens
• Phrases (bien sûr)
• Tout dans l'interface utilisateur, y compris les étiquettes de navigation, les boutons, les en-têtes

Meilleure pratique

• En règle générale, il est préférable d'éviter l'utilisation de TOUTES LES MAJUSCULES dans la plupart des types de contenu. Elles sont plus difficiles à parcourir et prennent plus de place. Bien que toutes les majuscules puissent transmettre de l'emphase, elles peuvent aussi donner l'impression de crier.
• Si un nom d'entreprise est entièrement en minuscules ou en majuscules, suivez leur style, même au début des phrases : DISH et bluecrux. En cas de doute, consultez le site web de l'entreprise.
• Utilisez la casse de titre pour les solutions Docker : Docker Extensions, Docker Hub.
• Mettez en majuscule un titre de poste s'il précède immédiatement un nom (Directeur général Scott Johnston).
• Ne mettez pas en majuscule un titre de poste qui suit un nom ou qui est une référence générique (Scott Johnston, directeur général de Docker).
• Mettez en majuscule les noms de département lorsque vous vous référez au nom d'un département, mais utilisez des minuscules si vous parlez du domaine de travail et non du département réel.
• Lorsque vous vous référez à un texte d'interface utilisateur spécifique, comme une étiquette de bouton ou un élément de menu, utilisez la même capitalisation que celle affichée dans l'interface utilisateur.

Contractions

Une contraction résulte de lettres omises du mot ou de la phrase d'origine, comme vous êtes pour vous êtes ou c'est pour cela est.

Conformément à notre approche conversationnelle, il est acceptable d'utiliser des contractions dans presque tous les types de contenu. Ne vous emballez pas. Trop de contractions dans une phrase peuvent la rendre difficile à lire.

Meilleure pratique

• Restez cohérent - ne passez pas des contractions à leurs équivalents épelés dans le corps du texte ou le texte de l'interface utilisateur.
• Évitez les contractions négatives (ne peut pas, ne fait pas, ne voudrait pas et ne devrait pas) autant que possible. Essayez de réécrire votre phrase pour l'aligner sur notre approche utile qui met l'accent sur les solutions, pas sur les problèmes.
• Ne contractez jamais un nom avec est, fait, a ou était car cela peut donner l'impression que le nom est possessif. Votre conteneur est prêt. Le conteneur de votre est prêt.

Modificateurs flottants

Évitez les modificateurs flottants, où le sujet du verbe d'une clause n'est pas clair :

• ❌ Après avoir activé la déconnexion automatique, vos utilisateurs sont déconnectés.
• ✅ Lorsque vous activez la déconnexion automatique, vos utilisateurs sont déconnectés.

Dates

Vous devez utiliser le format américain mois jour, année pour les dates : 26 juin 2021.

Lorsque cela est possible, utilisez le nom complet du mois (1er octobre 2022). S'il y a des contraintes d'espace, utilisez des abréviations de 3 lettres suivies d'un point (1er oct. 2022).

Décimales et fractions

Dans tout le contenu de l'interface utilisateur et la documentation technique, utilisez des décimales au lieu de fractions.

Meilleure pratique

• Portez toujours les décimales à au moins la centième place (33,76).
• Dans les tableaux, alignez les décimales sur le point décimal.
• Ajoutez un zéro avant le point décimal pour les fractions décimales inférieures à un (0,5 cm).

Listes

Les listes sont un excellent moyen de décomposer des idées complexes et de les rendre plus faciles à lire et à parcourir.

Meilleure pratique

• Les listes à puces doivent contenir relativement peu de mots ou de courtes phrases. Pour la plupart des types de contenu, limitez le nombre d'éléments dans une liste à cinq.

• N'ajoutez pas de virgules (,) ou de points-virgules (;) à la fin des éléments de la liste.

• Certains types de contenu peuvent utiliser des listes à puces contenant 10 éléments, mais il est préférable de diviser les listes plus longues en plusieurs listes, chacune avec son propre sous-titre ou introduction.

• Ne créez jamais une liste à puces avec une seule puce, et n'utilisez jamais un tiret pour indiquer une liste à puces.

• Si vos éléments de liste sont des fragments, mettez en majuscule les éléments de la liste pour faciliter la lecture, mais n'utilisez pas de ponctuation finale. Exemple:

  Je suis allé faire les courses pour acheter :

  • Lait
  • Farine
  • Oeufs

• Assurez-vous que tous vos éléments de liste sont parallèles. Cela signifie que vous devez structurer chaque élément de la liste de la même manière. Ils doivent tous être des fragments, ou ils doivent tous être des phrases complètes. Si vous commencez un élément de liste par un verbe, alors commencez chaque élément de liste par un verbe.

• Chaque élément de votre liste doit commencer par une lettre majuscule, sauf s'il s'agit de paramètres ou de commandes.

• Les listes séquentielles imbriquées sont étiquetées avec des lettres minuscules. Par exemple:

  1. Niveau supérieur
  2. Niveau supérieur
     1. Étape enfant
     2. Étape enfant

Nombres

Lorsque vous travaillez avec des nombres dans le contenu, les meilleures pratiques incluent :

• Épelez les nombres de un à neuf, sauf dans les unités de mesure telles que 4 Mo.
• Représentez les nombres avec deux chiffres ou plus comme des chiffres (10, 625, 773 925).
• Reformulez une phrase, plutôt que de la commencer par un nombre (sauf s'il s'agit d'une année).
• Lorsque vous citez des nombres dans un exemple, écrivez-les tels qu'ils apparaissent dans les captures d'écran d'accompagnement.
• Écrivez les nombres tels qu'ils apparaissent sur la plate-forme lorsque vous les citez dans un exemple.
• Pour vous référer à de grands nombres de manière abstraite (tels que des milliers, des millions et des milliards), utilisez une combinaison de mots et de nombres. N'abrégez pas les signifiants numériques.
• Évitez d'utiliser des virgules dans les nombres car elles peuvent représenter des décimales dans différentes cultures. Pour les nombres de cinq chiffres ou plus, utilisez un espace pour séparer.

  Correct	Incorrect
  1000	1,000
  14 586	14,586
  1 390 680	1,390,680

Versions

Lors de la rédaction des numéros de version pour les notes de version, utilisez l'exemple suivant :

• version 4.8.2
• v1.0
• Docker Hub API v2

Ponctuation

Deux-points et points-virgules

• Utilisez les deux-points pour : introduire une liste en ligne dans une phrase ; introduire une liste à puces ou numérotée ; et fournir une explication.
• N'utilisez pas de points-virgules. Utilisez plutôt deux phrases.

Virgules

• Utilisez la virgule de série ou d'Oxford - une virgule avant la conjonction de coordination (et, ou) dans une liste de trois choses ou plus.
• Si une série contient plus de trois éléments ou si les éléments sont longs, envisagez une liste à puces pour améliorer la lisibilité.

Tirets et traits d'union

• Utilisez le tiret cadratin (-) avec parcimonie lorsque vous voulez que le lecteur fasse une pause, pour créer des déclarations entre parenthèses ou pour souligner des mots ou des phrases spécifiques. Mettez toujours un espace de chaque côté du tiret cadratin.
• Utilisez un tiret demi-cadratin (-) pour indiquer des plages de nombres, de dates ou d'heures.
• Utilisez un trait d'union pour joindre deux mots ou plus pour former des adjectifs composés qui précèdent un nom. Le but de joindre des mots pour former un adjectif composé est de différencier le sens des adjectifs utilisés séparément (par exemple, 'documentation à jour', 'paiement forfaitaire' et 'armoire bien approvisionnée'. Vous pouvez également utiliser un trait d'union pour :
  • Éviter le redoublement maladroit des voyelles. Par exemple 'semi-indépendance*',* ou 'réélire'.
  • Empêcher la mauvaise lecture de certains mots. Par exemple 'Re-collecter' signifie collecter à nouveau ; sans trait d'union, le mot se remémorer a un sens différent.

Points d'exclamation

Évitez l'utilisation de points d'exclamation.

Parenthèses

N'utilisez pas de parenthèses dans la documentation technique. Elles peuvent réduire la lisibilité d'une phrase.