voice-and-language.md

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