mirror of https://github.com/knative/docs.git
74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
# 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 ...
|