Edit This Page

Documentation Style Guide

Cette page donne des directives de style d'écriture pour la documentation de Kubernetes. Ce sont des lignes directrices, pas des règles. Faites preuve de discernement et n'hésitez pas à proposer des modifications à ce document dans le cadre d'une pull request.

Pour plus d'informations sur la création de nouveau contenu pour les documents Kubernetes, suivez les instructions surl'utilisation des templates et création d'une pull request de documentation.

Note: La documentation de Kubernetes utilise Blackfriday Markdown Renderer ainsi que quelques Hugo Shortcodes pour prendre en charge les entrées de glossaire, les onglets et la représentation de l'état des fonctionnalités.

Language

La documentation de Kubernetes utilise l'anglais américain comme langue de référence.

Normes de formatage de la documentation

Utilisez le camel case pour les objets d'API

Lorsque vous faites référence à un objet API, utilisez les mêmes lettres majuscules et minuscules que celles utilisées dans le nom d'objet réel. Typiquement, les noms des objets de l'API utilisent le camel case.

Ne divisez pas le nom de l'objet API en mots séparés. Par exemple, utilisez PodTemplateList, et pas Pod Template List.

Référez-vous aux objets de l'API sans dire "objet", à moins que l'omission de "objet" n'entraîne une construction maladroite.

À faire À éviter
Le Pod dispose de deux conteneurs. La pod a deux conteneurs.
Le Deployment est responsable de ce qui suit ... L'objet Déployment est responsable de ...
Une PodList est une liste de Pod. Une Pod List est une liste de pods.
Les deux ContainerPorts ... Les deux objets ContainerPort ...
Les deux objets ContainerStateTerminated ... Les deux ContainerStateTerminateds ...

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents.

  1. Affiche des informations sur un Pod :

    kubectl describe pod <pod-name>

    where <pod-name> is the name of one of your Pods.

Use bold for user interface elements

À faire À éviter
Cliquez sur Fork. Cliquez sur "Fork".
Sélectionnez Other. Sélectionnez 'Other'.

Utiliser l'italique pour définir ou introduire de nouveaux termes.

À faire À éviter
Un cluster est un ensemble de nœuds ... Un "cluster" est un ensemble de nœuds ...
Ces composantes forment le control plane. Ces composantes forment le control plane.

Utiliser un style de code pour les noms de fichiers, les répertoires et les chemins d'accès

À faireÀ éviter
Open the envars.yaml file.Open the envars.yaml file.
Aller dans le répertoire /docs/tutorials.Go to the /docs/tutorials directory.
Open the /_data/concepts.yaml file.Open the /_data/concepts.yaml file.

Utiliser la norme internationale pour la ponctuation entre guillemets

À faire À éviter
events are recorded with an associated "stage". events are recorded with an associated "stage."
The copy is called a "fork". The copy is called a "fork."

Inline code formatting

Use code style for inline code and commands

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).

À faireÀ éviter
The kubectl run command creates a Deployment.The "kubectl run" command creates a Deployment.
For declarative management, use kubectl apply.For declarative management, use "kubectl apply".
Enclose code samples with triple backticks. (```)Enclose code samples with any other syntax.
Note: Le site Web prend en charge la coloration syntaxique pour les échantillons de code, mais la spécification d'une langue est facultative.

Utiliser le style de code pour les noms de champs d'objets

À faireÀ éviter
Set the value of the replicas field in the configuration file.Définissez la valeur du champ "replicas" dans le fichier de configuration.
The value of the exec field is an ExecAction object.La valeur du champ "exec" est un objet ExecAction.

Utiliser le style normal pour les chaînes de caractères et les valeurs de champs entiers

Pour les valeurs de champ de type chaîne de caractères ou entier, utilisez un style normal sans guillemets.

À faire À éviter
Set the value of imagePullPolicy to Always. Set the value of imagePullPolicy to "Always".
Set the value of image to nginx:1.8. Set the value of image to nginx:1.8.
Set the value of the replicas field to 2. Set the value of the replicas field to 2.

Code snippet formatting

Ne pas inclure l'invite de commande

À faire À éviter
kubectl get pods $ kubectl get pods

Séparer les commandes de la sortie

Vérifiez que le Pod fonctionne sur le nœud que vous avez choisi :

kubectl get pods --output=wide

La sortie est similaire à celle-ci :

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Versioning Kubernetes examples

Code examples and configuration examples that include version information should be consistent with the accompanying text.

If the information is version specific, the Kubernetes version needs to be defined in the prerequisites section of the Task template or the [Tutorial template] (/docs/contribute/style/page-templates/#tutorial-template). Once the page is saved, the prerequisites section is shown as Before you begin.

Pour spécifier la version de Kubernetes pour une tâche ou une page de tutoriel, incluez min-kubernetes-server-version dans l'entête de la page.

Si l'exemple YAML se trouve dans un fichier autonome, recherchez et passez en revue les sujets qui l'incluent comme référence. Vérifiez que toutes les rubriques utilisant le YAML autonome ont les informations de version appropriées définies. Si un fichier YAML autonome n'est référencé à partir d'aucun sujet, pensez à le supprimer au lieu de le mettre à jour.

Par exemple, si vous écrivez un tutoriel pertinent pour Kubernetes version 1.8, la première partie de votre fichier de démarque doit ressembler à ceci :

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

Dans les exemples de code et de configuration, n'incluez pas de commentaires sur les versions alternatives. Veillez à ne pas inclure d'énoncés incorrects dans vos exemples sous forme de commentaires, tels que :

apiVersion: v1 # earlier versions use...
kind: Pod
...

Liste de mots Kubernetes.io

Une liste de termes et de mots spécifiques à Kubernetes à utiliser de manière cohérente sur le site.

Term Usage
Kubernetes Kubernetes a toujours une majuscule.
Docker Docker a toujours une majuscule.
SIG Docs SIG Docs plutôt que SIG-DOCS ou d'autres variantes.

Shortcodes

Hugo Shortcodes help create different rhetorical appeal levels. Notre documentation prend en charge trois shortcodes différents dans cette catégorie : Note {{< note >}}, Mise en garde {{< caution >}}, et Avertissement {{< warning >}}.

  1. Entourez le texte d'un raccourci d'ouverture et de fermeture.

  2. Utilisez la syntaxe suivante pour appliquer un style :

    {{< note >}}
Il n'est pas nécessaire d'inclure un préfixe ; le shortcode fournit automatiquement (Note:, Caution:, etc.).
{{< /note >}}

La sortie est :

Note: Le préfixe que vous choisissez est le même que le texte de la balise.

Note

Utilisez {{< note *//>}} pour mettre en surbrillance un conseil ou une information qu'il peut être utile de connaître.

Par exemple :

{{</* note >}}
Vous pouvez _toujours_ utiliser Markdown à l'intérieur de ces légendes.
{{< /note >}}

La sortie est :

Note: Vous pouvez toujours utiliser Markdown à l'intérieur de ces légendes.

Mise en garde

Utilisez {{< caution *//>}} pour attirer l'attention sur une information importante afin d'éviter les pièges.

Par exemple :

{{</* caution >}}
Le style de légende ne s'applique qu'à la ligne directement au-dessus de la balise.
{{< /caution >}}

La sortie est :

Avertissement: Le style de légende ne s'applique qu'à la ligne directement au-dessus de la balise.

Avertissement

Utilisez {{< warning *//>}} pour indiquer un danger ou une information cruciale à suivre.

Par exemple :

{{</* warning >}}
Méfiez-vous.
{{< /warning >}}

La sortie est :

Attention: Méfiez-vous.

Katacoda Embedded Live Environment

Ce bouton permet aux utilisateurs d'exécuter Minikube dans leur navigateur en utilisant le Katacoda Terminal. Il abaisse le seuil d'entrée en permettant aux utilisateurs d'utiliser Minikube en un seul clic au lieu de passer par l'ensemble du processus d'installation Minikube et Kubectl localement.

The Embedded Live Environment is configured to run minikube start and lets users complete tutorials in the same window as the documentation.

Avertissement: La session est limitée à 15 minutes.

For example:

{{< kat-button >}}

La sortie est :

Common Shortcode Issues

Ordered Lists

Un Shortcode interrompra les listes numérotées à moins que vous ne mettiez une indentation de 4 espaces avant l'avis et l'étiquette.

Par exemple :

1. Préchauffer le four à 350˚F

1. Préparer la pâte et la verser dans un moule à charnière.
   {{< note >}}**Note:** Graisser la casserole pour de meilleurs résultats.{{< /note >}}

1. Cuire au four de 20 à 25 minutes ou jusqu'à ce que ce soit pris.

La sortie est :

  1. Préchauffer le four à 350˚F

  2. Préparer la pâte et la verser dans un moule à charnière.

    Note: Graisser la casserole pour de meilleurs résultats.

  3. Cuire au four de 20 à 25 minutes ou jusqu'à ce que ce soit pris.

Expressions Includes

Les Shortcodes dans les expressions d'include brisera la compilation du site. Vous devez les insérer dans le document parent, avant et après avoir appelé l'include. Par exemple :

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Meilleures pratiques en matière de contenu

Cette section contient des suggestions de pratiques exemplaires pour un contenu clair, concis et cohérent.

Utiliser le présent

À faire À éviter
Cette commande lance un proxy. Cette commande lancera un proxy.

Exception : Utilisez le futur ou le passé s'il est nécessaire pour transmettre le sens correct.

Utiliser la voix active

À faire À éviter
Vous pouvez explorer l'API à l'aide d'un navigateur. L'API peut être explorée à l'aide d'un navigateur.
Le fichier YAML spécifie le nombre de répliques. Le nombre de répliques est spécifié dans le fichier YAML.

Exception : Utilisez la voix passive si la voix active conduit à une construction maladroite.

Utiliser un langage simple et direct

Utilisez un langage simple et direct. Évitez d'utiliser des expressions inutiles, comme "s'il vous plaît".

À faire À éviter
Pour créer un ReplicaSet, ... Afin de créer un ReplicaSet, ...
Voir le fichier de configuration. Veuillez consulter le fichier de configuration.
Voir les Pods. Avec cette prochaine commande, nous allons voir les Pods.

S'adresser au lecteur en tant que "vous"

À faire À éviter
Vous pouvez créer un déploiement en ... Nous allons créer un déploiement en ...
Dans l'édition précédente, vous pouvez voir... Dans la sortie précédente, on peut voir ...

Évitez les phrases latines

Préférez les termes français aux abréviations latines.

À faire À éviter
Par exemple, ... e.g., ...
C'est à dire, ... i.e., ...

Exception : Utilisez "etc." pour et cetera.

Tendances à éviter

Évitez d'utiliser "nous"

L'utilisation du "nous" dans une phrase peut prêter à confusion, car le lecteur pourrait ne pas savoir s'ils font partie du "nous" que vous décrivez.

À faire À éviter
La version 1.4 comprend ... Dans la version 1.4, nous avons ajouté ...
Kubernetes offre une nouvelle fonctionnalité pour ... Nous proposons une nouvelle fonctionnalité ...
Cette page vous apprend à utiliser les Pods. Dans cette page, nous allons en savoir plus sur les Pods.

Évitez le jargon et les expressions idiomatiques

Certains lecteurs parlent le français comme seconde langue. Évitez le jargon et les expressions idiomatiques pour les aider à mieux comprendre.

À faire À éviter
En interne, ... Sous le capot, ...
Créer un nouveau cluster. Monter un nouveau cluster.

Évitez les déclarations sur l'avenir

Évitez de faire des promesses ou de donner des conseils sur l'avenir. Si vous avez besoin de parler d'une fonctionnalité alpha, placez le texte sous un titre qui l'identifie comme une fonctionnalité alpha.

Évitez les déclarations qui seront bientôt périmées

Évitez les mots comme "actuellement" et "nouveau". Une caractéristique qui est nouvelle aujourd'hui pourrait ne pas être considérée comme nouvelle dans quelques mois.

À faire À éviter
Dans la version 1.4, ... Dans la version actuelle, ...
La fonction de fédération offre ... La nouvelle fonctionnalité de la Fédération offre ...

A suivre