Commit bd86b61a authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'eread/add-second-person-to-style-guide' into 'master'

Add guidance for using second person in documentation style guide

See merge request gitlab-org/gitlab!75580
parents f61e3c5d cbc56138
......@@ -703,6 +703,14 @@ Do not use **type** if you can avoid it. Use **enter** instead.
Do not use **useful**. If the user doesn't find the process to be useful, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml))
## user, users
When possible, address the reader directly, instead of calling them **users**.
Use the [second person](#you-your-yours), **you**, instead.
- Do: You can configure a pipeline.
- Do not: Users can configure a pipeline.
## utilize
Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand.
......@@ -729,5 +737,13 @@ One exception: You can use **we recommend** instead of **it is recommended** or
Do not use **whitelist**. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## you, your, yours
Use **you**, **your**, and **yours** instead of [**the user** and **the user's**](#user-users).
Documentation should be from the [point of view](https://design.gitlab.com/content/voice-tone#point-of-view) of the reader.
- Do: You can configure a pipeline.
- Do not: Users can configure a pipeline.
<!-- vale on -->
<!-- markdownlint-enable -->
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment