Voice and language¶

Use present tense¶

Correct	Incorrect
This command starts a proxy.	This command will start a proxy.

Use active voice¶

Correct	Incorrect
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.

Use simple and direct language¶

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

Correct	Incorrect
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", not "we"¶

Correct	Incorrect
You can create a `Deployment` by ...	We can create a `Deployment` by ...
In the preceding output, you can see...	In the preceding output, we can see ...
This page teaches you how to use pods.	In this page, we are going to learn about pods.

Avoid jargon, idioms, and Latin¶

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

Correct	Incorrect
Internally, ...	Under the hood, ...
Create a new cluster.	Turn up a new cluster.
Initially, ...	Out of the box, ...
For example, ...	e.g., ...
Enter through the gateway ...	Enter via the gateway ...

Avoid statements about the future¶

Avoid making promises or giving hints about the future. If you need to talk about a feature in development, add a boilerplate under the front matter that identifies the information accordingly.

Avoid statements that will soon be out of date¶

Avoid using wording that becomes outdated quickly like "currently" and "new". A feature that is new today is not new for long.

Correct	Incorrect
In version 1.4, ...	In the current version, ...
The Federation feature provides ...	The new Federation feature provides ...

Avoid words that assume a specific level of understanding¶

Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value.

Correct	Incorrect
Include one command in ...	Include just one command in ...
Run the container ...	Simply run the container ...
You can remove ...	You can easily remove ...
These steps ...	These simple steps ...