website/docs/contribute/style-guide.md

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

For additional information on creating new content for the Kubernetes docs, follow the instructions on using page templates and creating a documentation pull request. {% endcapture %}

{% capture body %}

Documentation formatting standards

Capitalize API objects

Capitalize the names of API objects. Refer to API objects without saying "object."

Do	Don't
The Pod has two Containers.	The pod has two containers.
The Deployment is responsible for ...	The Deployment object is responsible for ...

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 <pod-name>
   

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

Use bold for user interface elements

Do	Don't
Click Fork.	Click "Fork".
Select Other.	Select 'Other'.

Use italics to define or introduce new terms

Do	Don'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

Do	Don'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.

Code snippet 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 (`).

Do	Don't
Set the value of the replicas field in the configuration file.	Set the value of the "replicas" field in the configuration file.
The kubectl run command creates a Deployment.	The "kubectl run" command creates a Deployment.

Don't include the command prompt

Do	Don'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

{% comment %}## Kubernetes.io word list

A list of Kubernetes-specific terms and words to be used consistently across the site.

Term	Useage
TBD	TBD

{% endcomment %}

Content best practices

This section contains suggested best practices for clear, concise, and consistent content.

Use present tense

Do	Don't
This command starts a proxy.	This command will start a proxy.

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

Do	Don't
You can explore the API using a browser.	The API can be explored using a browser.
The YAML file specifies the replica count.	The replica count is specified in the YAML file.

Exception: Use passive voice if active voice leads to an awkward construction.

Use simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."

Do	Don't
To create a ReplicaSet, ...	In order to create a ReplicaSet, ...
See the configuration file.	Please see the configuration file.
View the Pods.	With this next command, we'll view the Pods.

Address the reader as "you"

Do	Don't
You can create a Deployment by ...	We'll create a Deployment by ...
In the preceding output, you can see...	In the preceding output, we can see ...

Patterns to avoid

Avoid using "we"

Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" you're describing.

Do	Don't
Version 1.4 includes ...	In version 1.4, we have added ...
Kubernetes provides a new feature for ...	We provide a new feature ...
This page teaches you how to use pods.	In this page, we are going to learn about pods.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.

Do	Don't
Internally, ...	Under the hood, ...
Create a new cluster.	Turn up a new cluster.

Avoid statements about the future

Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.

Avoid statements that will soon be out of date

Avoid words like "currently" and "new." A feature that is new today might not be considered new in a few months.

Do	Don't
In version 1.4, ...	In the current version, ...
The Federation feature provides ...	The new Federation feature provides ...

{% endcapture %}

{% capture whatsnext %}

• Learn about writing a new topic.
• Learn about using page templates.
• Learn about staging your changes
• Learn about creating a pull request. {% endcapture %}

{% include templates/concept.md %}