Guide de formatage

En-têtes et sous-en-têtes

Les lecteurs accordent un peu plus d'attention aux en-têtes, aux listes à puces et aux liens, il est donc important de s'assurer que les deux ou trois premiers mots de ces éléments "chargent" l'information autant que possible.

Meilleure pratique

• Les en-têtes et sous-en-têtes doivent permettre au lecteur de savoir ce qu'il trouvera sur la page.
• Ils doivent décrire succinctement et précisément de quoi traite le contenu.
• Les en-têtes doivent être courts (pas plus de huit mots), directs et rédigés dans un langage simple et actif.
• Vous devriez éviter les jeux de mots, les aguiches et les références culturelles.
• Omettez les articles de tête (un, le, etc.)

Titre de la page

Les titres de page doivent être orientés vers l'action. Par exemple : - Activer SCIM - Installer Docker Desktop

Meilleure pratique

• Assurez-vous que le titre de votre page et l'entrée de la table des matières (TOC) correspondent.
• Si vous voulez utiliser un ‘:’ dans un titre de page dans la table des matières (_toc.yaml), vous devez entourer tout le titre de “” pour éviter de casser la construction.
• Si vous ajoutez une nouvelle entrée au fichier TOC, assurez-vous qu'elle se termine par une barre oblique (/). Si ce n'est pas le cas, la page n'affichera pas la navigation latérale.

Images

Les images, y compris les captures d'écran, peuvent aider un lecteur à mieux comprendre un concept. Cependant, vous devez les utiliser avec parcimonie car elles ont tendance à devenir obsolètes.

Meilleure pratique

• Lorsque vous prenez des captures d'écran :
  • N'utilisez pas de texte lorem ipsum. Essayez de reproduire comment quelqu'un utiliserait la fonctionnalité dans un scénario réel, et utilisez un texte réaliste.
  • Ne capturez que l'interface utilisateur pertinente. N'incluez pas d'espace blanc inutile ou de zones de l'interface utilisateur qui n'aident pas à illustrer le point.
  • Gardez-le petit. Si vous n'avez pas besoin de montrer toute la largeur de l'écran, ne le faites pas.
  • Examinez comment l'image s'affiche sur la page. Assurez-vous que l'image n'est pas floue ou écrasante.
  • Soyez cohérent. Coordonnez les captures d'écran avec les autres captures d'écran déjà présentes sur une page de documentation pour une expérience de lecture cohérente.
  • Pour garder le dépôt Git léger, compressez les images (sans perte). Assurez-vous de compresser les images avant de les ajouter au dépôt. Compresser les images après les avoir ajoutées au dépôt aggrave en fait l'impact sur le dépôt Git (cependant, cela optimise toujours la bande passante lors de la navigation).
  • N'oubliez pas de supprimer du dépôt les images qui ne sont plus utilisées.

Pour plus d'informations sur la façon d'ajouter des images à votre contenu, consultez Exemples de composants et de formatage utiles.

Liens

Faites attention à ne pas créer trop de liens, surtout dans le corps du texte. Des liens excessifs peuvent être distrayants ou éloigner les lecteurs de la page actuelle.

Lorsque les gens suivent des liens, ils peuvent souvent perdre le fil de leur pensée et ne pas retourner à la page d'origine, même s'ils n'ont pas absorbé toutes les informations qu'elle contient.

Les meilleurs liens offrent aux lecteurs une autre façon de parcourir les informations.

Meilleure pratique

• Utilisez un langage simple qui n'induit pas en erreur ou ne promet pas trop.
• Soyez court et descriptif (environ cinq mots est le mieux).
• Permettez aux gens de prédire (avec un bon degré de confiance) ce qu'ils obtiendront s'ils sélectionnent un lien. Reproduisez le texte de l'en-tête sur la page de destination dans les liens autant que possible.
• Chargez à l'avant les termes orientés utilisateur et action au début du lien (Téléchargez notre application).
• Évitez les appels à l'action génériques (tels que cliquez ici, en savoir plus).
• N'incluez aucune ponctuation finale lorsque vous hyperliez du texte (par exemple, des points, des points d'interrogation ou des points d'exclamation).
• Ne mettez pas le texte du lien en italique ou en gras, sauf s'il le serait dans le corps du texte normal.

Pour plus d'informations sur la façon d'ajouter des liens à votre contenu, consultez Exemples de composants et de formatage utiles.

Code et échantillons de code

Formatez les éléments suivants comme du code : commandes Docker, instructions et noms de fichiers (noms de paquets).

Pour appliquer le style de code en ligne, entourez le texte d'un seul backtick (`).

Pour plus d'informations sur la façon d'ajouter des blocs de code à votre contenu, consultez Exemples de composants et de formatage utiles.

Meilleure pratique pour les commandes

• Invite de commande et shell :
  • Pour un shell non privilégié, préfixez les commandes dans les blocs de code avec le symbole d'invite $.
  • Pour un shell privilégié, préfixez les commandes dans les blocs de code avec le symbole d'invite #.
  • Pour un shell distant, ajoutez le contexte de la machine distante et excluez le chemin. Par exemple, utilisateur@hôte $.
  • Spécifiez le shell Windows (Invite de commandes, PowerShell ou Git Bash), lorsque vous ajoutez une commande spécifique à Windows. Il n'est pas nécessaire d'inclure une commande pour chaque shell Windows.
  • Utilisez des onglets lorsque vous ajoutez des commandes pour plusieurs systèmes d'exploitation ou shells. Pour plus d'informations sur la façon d'ajouter des onglets à votre contenu, consultez Onglets.
• Commandes que les utilisateurs copieront et exécuteront :
  • Ajoutez une seule commande par bloc de code si une commande produit une sortie ou nécessite que l'utilisateur vérifie les résultats.
  • Ajoutez la sortie de la commande à un bloc de code distinct de la commande.
• Commandes que les utilisateurs ne copieront pas et n'exécuteront pas :
  • Utilisez une syntaxe compatible POSIX. Il n'est pas nécessaire d'inclure la syntaxe Windows.
  • Entourez les arguments facultatifs de crochets ( [ ] ).
  • Utilisez des barres verticales ( | ) entre les arguments mutuellement exclusifs.
  • Utilisez trois points ( ... ) après des arguments répétés.

Meilleure pratique pour le code

• Indentez les blocs de code de 3 espaces lorsque vous imbriquez un bloc de code sous un élément de liste.
• Utilisez trois points ( ... ) lorsque vous omettez du code.

Avertissements

Utilisez des avertissements pour mettre en évidence des informations sélectionnées sur une page.

Meilleure pratique

• Formatez les mots Avertissement, Important ou Note en gras. Ne mettez pas en gras le contenu de l'avertissement.
• Il est de bonne pratique d'éviter de placer beaucoup d'avertissements textuels sur une seule page. Ils peuvent créer une apparence encombrée s'ils sont utilisés à l'excès, et vous diminuerez leur impact.

Pour plus d'informations sur la façon d'ajouter des avertissements à votre contenu, consultez Exemples de composants et de formatage utiles.

Navigation

Lorsque vous documentez comment naviguer dans l'interface utilisateur de Docker Desktop ou Docker Hub :

• Utilisez toujours l'emplacement, puis l'action. Par exemple : Dans la liste déroulante Visibilité (emplacement), sélectionnez Public (action).
• Soyez bref et précis. Par exemple : Faire : Sélectionnez Enregistrer. Ne pas faire : Sélectionnez Enregistrer pour que les modifications prennent effet.
• Si une étape doit inclure une raison, commencez l'étape avec elle. Cela aide l'utilisateur à parcourir plus rapidement. Faire : Pour voir les modifications, dans la demande de fusion, sélectionnez le lien. Ne pas faire : Sélectionnez le lien dans la demande de fusion pour voir les modifications

Étapes facultatives

Si une étape est facultative, commencez l'étape par le mot Facultatif suivi d'un point.

Par exemple :

1. Facultatif. Entrez une description pour la tâche.

Texte de remplacement

Vous voudrez peut-être fournir une commande ou une configuration qui utilise des valeurs spécifiques.

Dans ces cas, utilisez < et > pour indiquer où un lecteur doit remplacer le texte par sa propre valeur. Par exemple :

docker extension install <nom-de-votre-extension>

Tableaux

Utilisez des tableaux pour décrire des informations complexes de manière simple.

Notez que dans de nombreux cas, une liste non ordonnée est suffisante pour décrire une liste d'éléments avec une seule description simple par élément. Mais, si vous avez des données qui sont mieux décrites par une matrice, les tableaux sont le meilleur choix.

Meilleure pratique

• Utilisez la casse de phrase pour les en-têtes de tableau.
• Pour garder les tableaux accessibles et scannables, les tableaux ne doivent pas avoir de cellules vides. S'il n'y a pas de valeur significative pour une cellule, envisagez d'entrer N/A pour 'non applicable' ou Aucun.

Pour plus d'informations sur la façon d'ajouter des tableaux à votre contenu, consultez Exemples de composants et de formatage utiles.

Se référer aux types de fichiers

Lorsque vous discutez d'un type de fichier, utilisez le nom formel du type. N'utilisez pas l'extension de fichier pour vous référer génériquement au type de fichier.

| Correct | Incorrect |
| --- | --- |
| un fichier PNG | un fichier .png |
| un fichier Bash | un fichier .sh |

Se référer aux unités

Lorsque vous vous référez à des unités de mesure, utilisez la forme abrégée en majuscules, avec un espace entre la valeur et l'unité. Par exemple :

| Correct | Incorrect |
| --- | --- |
| 10 Go | 10Go |
| 10 Go | 10 go |
| 10 Go | 10 gigaoctets |