Skip to content

G
gitlab-ce
Commit 33b0a115 authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Nick Gaskill
Browse files
Options

Moved more words to words list

parent 15ee1a41
Hide whitespace changes
Inline Side-by-side
Showing with 45 additions and 76 deletions
doc/development/documentation/styleguide/index.md
View file @ 33b0a115
...@@ -304,7 +304,6 @@ GitLab documentation should be clear and easy to understand. Avoid unnecessary w ...@@ -304,7 +304,6 @@ GitLab documentation should be clear and easy to understand. Avoid unnecessary w
- Be clear, concise, and stick to the goal of the topic. - Be clear, concise, and stick to the goal of the topic.
- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) - Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).)
- Use [inclusive language](#inclusive-language).
- Rewrite to avoid wordiness: - Rewrite to avoid wordiness:
- there is - there is
- there are - there are
...@@ -385,80 +384,6 @@ references to user interface elements. For example: ...@@ -385,80 +384,6 @@ references to user interface elements. For example:
- To sign in to product X, enter your credentials, and then select **Log in**. - To sign in to product X, enter your credentials, and then select **Log in**.
### Inclusive language
We strive to create documentation that's inclusive. This section includes
guidance and examples for these categories:
- [Gender-specific wording](#avoid-gender-specific-wording).
(Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).)
- [Ableist language](#avoid-ableist-language).
(Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).)
- [Cultural sensitivity](#culturally-sensitive-language).
(Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).)
We write our developer documentation with inclusivity and diversity in mind. This
page is not an exhaustive reference, but describes some general guidelines and
examples that illustrate some best practices to follow.
#### Avoid gender-specific wording
When possible, use gender-neutral pronouns. For example, you can use a singular
[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as
a gender-neutral pronoun.
Avoid the use of gender-specific pronouns, unless referring to a specific person.
<!-- vale gitlab.InclusionGender = NO -->
| Use | Avoid |
|-----------------------------------|---------------------------------|
| People, humanity | Mankind |
| GitLab Team Members | Manpower |
| You can install; They can install | He can install; She can install |
<!-- vale gitlab.InclusionGender = YES -->
If you need to set up [Fake user information](#fake-user-information), use
diverse or non-gendered names with common surnames.
#### Avoid ableist language
Avoid terms that are also used in negative stereotypes for different groups.
<!-- vale gitlab.InclusionAbleism = NO -->
| Use | Avoid |
|------------------------|----------------------|
| Check for completeness | Sanity check |
| Uncertain outliers | Crazy outliers |
| Slows the service | Cripples the service |
| Placeholder variable | Dummy variable |
| Active/Inactive | Enabled/Disabled |
| On/Off | Enabled/Disabled |
<!-- vale gitlab.InclusionAbleism = YES -->
Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language)
in the Google Developer Style Guide.
#### Culturally sensitive language
Avoid terms that reflect negative cultural stereotypes and history. In most
cases, you can replace terms such as `master` and `slave` with terms that are
more precise and functional, such as `primary` and `secondary`.
<!-- vale gitlab.InclusionCultural = NO -->
| Use | Avoid |
|----------------------|-----------------------|
| Primary / secondary | Master / slave |
| Allowlist / denylist | Blacklist / whitelist |
<!-- vale gitlab.InclusionCultural = YES -->
For more information see the [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02).
### Fake user information ### Fake user information
You may need to include user information in entries such as a REST call or user profile. You may need to include user information in entries such as a REST call or user profile.
......
doc/development/documentation/styleguide/word_list.md
View file @ 33b0a115
...@@ -32,6 +32,10 @@ Instead of **and/or**, use or or rewrite the sentence to spell out both options. ...@@ -32,6 +32,10 @@ Instead of **and/or**, use or or rewrite the sentence to spell out both options.
Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead.
## blacklist
Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## currently ## currently
Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml))
...@@ -43,6 +47,11 @@ to mean someone who is assigned the Developer role. Instead, write it out. "If y ...@@ -43,6 +47,11 @@ to mean someone who is assigned the Developer role. Instead, write it out. "If y
Do not use "Developer permissions." A user who is assigned the Developer role has a set of associated permissions. Do not use "Developer permissions." A user who is assigned the Developer role has a set of associated permissions.
## disable
See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance.
Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
## easily ## easily
Do not use. If the user doesn't find the process to be these things, we lose their trust. Do not use. If the user doesn't find the process to be these things, we lose their trust.
...@@ -51,6 +60,11 @@ Do not use. If the user doesn't find the process to be these things, we lose the ...@@ -51,6 +60,11 @@ Do not use. If the user doesn't find the process to be these things, we lose the
Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml))
## enable
See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance.
Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
## future tense ## future tense
When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml))
...@@ -89,6 +103,18 @@ to mean someone who is assigned the Maintainer role. Instead, write it out. "If ...@@ -89,6 +103,18 @@ to mean someone who is assigned the Maintainer role. Instead, write it out. "If
Do not use "Maintainer permissions." A user who is assigned the Maintainer role has a set of associated permissions. Do not use "Maintainer permissions." A user who is assigned the Maintainer role has a set of associated permissions.
## mankind
Do not use. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml))
## manpower
Do not use. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml))
## master
Do not use. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## may, might ## may, might
**Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**.
...@@ -127,6 +153,10 @@ Do not use "Reporter permissions." A user who is assigned the Reporter role has ...@@ -127,6 +153,10 @@ Do not use "Reporter permissions." A user who is assigned the Reporter role has
Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions.
## sanity check
Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
## scalability ## scalability
Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page.
...@@ -139,6 +169,10 @@ Do not use. If the user doesn't find the process to be these things, we lose the ...@@ -139,6 +169,10 @@ Do not use. If the user doesn't find the process to be these things, we lose the
Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed.
## slave
Do not use. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## subgroup ## subgroup
Use instead of `sub-group`. Use instead of `sub-group`.
...@@ -147,6 +181,12 @@ Use instead of `sub-group`. ...@@ -147,6 +181,12 @@ Use instead of `sub-group`.
Do not use. Example: `the file that you save` can be `the file you save`. Do not use. Example: `the file that you save` can be `the file you save`.
## they
Avoid the use of gender-specific pronouns, unless referring to a specific person.
Use a singular [they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as
a gender-neutral pronoun.
## useful ## useful
Do not use. If the user doesn't find the process to be these things, we lose their trust. Do not use. If the user doesn't find the process to be these things, we lose their trust.
...@@ -159,5 +199,9 @@ Do not use. Use **use** instead. It's more succinct and easier for non-native En ...@@ -159,5 +199,9 @@ Do not use. Use **use** instead. It's more succinct and easier for non-native En
Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml))
## whitelist
Do not use. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
<!-- vale on --> <!-- vale on -->
<!-- markdownlint-enable --> <!-- markdownlint-enable -->
doc/development/experiment_guide/gitlab_experiment.md
View file @ 33b0a115
...@@ -588,7 +588,7 @@ When there is no experiment data in the `window.gon.experiment` object for the g ...@@ -588,7 +588,7 @@ When there is no experiment data in the `window.gon.experiment` object for the g
NOTE: NOTE:
We use the terms "enabled" and "disabled" here, even though it's against our We use the terms "enabled" and "disabled" here, even though it's against our
[documentation style guide recommendations](../documentation/styleguide/index.md#avoid-ableist-language) [documentation style guide recommendations](../documentation/styleguide/word_list.md#enable)
because these are the terms that the feature flag documentation uses. because these are the terms that the feature flag documentation uses.
You may already be familiar with the concept of feature flags in GitLab, but using You may already be familiar with the concept of feature flags in GitLab, but using
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7