Voice and language
Voice and language
Use present tense
This command starts a proxy.
This command will start a proxy.
Use active voice
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 phrases, such as saying
"please."
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" (Avoid using "we")
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 ...
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.
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.
In version 1.4, ...
In the current version, ...
The Federation feature provides ...
The new Federation feature provides ...
Correct
Incorrect