# Voice and language

## Use present tense

|:white_check_mark: Correct                           |:no_entry: Incorrect
|-----------------------------|------
|This command starts a proxy. | This command will start a proxy.

## Use active voice

|:white_check_mark: Correct                                         |:no_entry: 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".

|:white_check_mark: Correct                          |:no_entry: 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"

|:white_check_mark: Correct                                     |:no_entry: 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.

|:white_check_mark: Correct                    |:no_entry: 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.

|:white_check_mark: Correct                                  |:no_entry: 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.

|:white_check_mark: Correct                    |:no_entry: 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 ...