This page gives writing style guidelines for the Gardener documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Language

Gardener documentation uses US English.

Documentation formatting standards

Use camel case for API objects

When you refer to an API object, use the same uppercase and lowercase letters that are used in the actual object name. Typically, the names of API objects use camel case.

Don’t split the API object name into separate words. For example, use PodTemplateList, not Pod Template List.

Refer to API objects without saying “object,” unless omitting “object” leads to an awkward construction.

DoDon't
The Pod has two containers.The pod has two containers.
The Deployment is responsible for ...The Deployment object is responsible for ...
A PodList is a list of Pods.A Pod List is a list of pods.
The two ContainerPorts ...The two ContainerPort objects ...
The two ContainerStateTerminated objects ...The two ContainerStateTerminateds ...

Use angle brackets for placeholders

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

  1. Display information about a pod:

    kubectl describe pod

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

Use bold for user interface elements

DoDon't
Click Fork.Click "Fork".
Select Other.Select 'Other'.

Use italics to define or introduce new terms

DoDon't
A cluster is a set of nodes ...A "cluster" is a set of nodes ...
These components form the control plane.These components form the control plane.

Use code style for filenames, directories, and paths

DoDon't
Open the envars.yaml file.Open the envars.yaml file.
Go to the /docs/tutorials directory.Go to the /docs/tutorials directory.
Open the /_data/concepts.yaml file.Open the /_data/concepts.yaml file.

Use the international standard for punctuation inside quotes

DoDon't
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 (`).

DoDon't
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".

Use code style for object field names

DoDon't
Set the value of the replicas field in the configuration file.Set the value of the "replicas" field in the configuration file.
The value of the exec field is an ExecAction object.The value of the "exec" field is an ExecAction object.

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

DoDon't
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

Don’t include the command prompt

DoDon't
kubectl get pods$ kubectl get pods

Separate commands from output

Verify that the pod is running on your chosen node:

kubectl get pods --output=wide

The output is similar to this:

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. Identify the Kubernetes version in the Before you begin section.

To specify the Kubernetes version for a task or tutorial page, include min-kubernetes-server-version in the front matter of the page.

If the example YAML is in a standalone file, find and review the topics that include it as a reference. Verify that any topics using the standalone YAML have the appropriate version information defined. If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.

For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:

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

In code and configuration examples, do not include comments about alternative versions. Be careful to not include incorrect statements in your examples as comments, such as:

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

Report an issue

See a typo? Have a picture to recommend? Want to edit some words/phrases/sentences? You can simply submit a ticket to request we make the change. If you are github savvy, submit a pull request. Open Github Issue