diff options
Diffstat (limited to 'doc/development/documentation/styleguide/word_list.md')
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 214 |
1 files changed, 208 insertions, 6 deletions
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 3fba9078bab..9e921bb30f0 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -17,6 +17,12 @@ For guidance not on this page, we defer to these style guides: <!-- vale off --> <!-- markdownlint-disable --> +## @mention + +Try to avoid. Say "mention" instead, and consider linking to the +[mentions topic](../../../user/project/issues/issue_data_and_actions.md#mentions). +Don't use `code formatting`. + ## above Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. @@ -35,6 +41,13 @@ Try to avoid, unless you are talking about security-related features. For exampl This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). +## Alpha + +Uppercase. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** + +You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +in the handbook when writing about Alpha features. + ## and/or Instead of **and/or**, use or or rewrite the sentence to spell out both options. @@ -43,10 +56,29 @@ 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. +## Beta + +Uppercase. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** + +You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +in the handbook when writing about Beta features. + ## 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)) +## board + +Use lowercase for **boards**, **issue boards**, and **epic boards**. + +## checkbox + +One word, **checkbox**. Do not use **check box**. + +## CI/CD + +Always uppercase. No need to spell out on first use. + ## 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)) @@ -56,6 +88,7 @@ Do not use when talking about the product or its features. The documentation des When writing about the Developer role: - Use a capital **D**. +- Do not use bold. - Do not use the phrase, **if you are a developer** to mean someone who is assigned the Developer role. Instead, write it out. For example, **if you are assigned the Developer role**. - To describe a situation where the Developer role is the minimum required: @@ -69,6 +102,13 @@ Do not use **Developer permissions**. A user who is assigned the Developer role 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)) +## earlier + +Use when talking about version numbers. + +- Avoid: In GitLab 14.1 and lower. +- Use instead: In GitLab 14.1 and earlier. + ## easily Do not use. If the user doesn't find the process to be easy, we lose their trust. @@ -86,24 +126,51 @@ Do not use **e-mail** with a hyphen. When plural, use **emails** or **email mess 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)) +## epic + +Lowercase. + +## epic board + +Lowercase. + +## etc. + +Try to avoid. Be as specific as you can. Do not use **and so on** as a replacement. + +- Avoid: You can update objects, like merge requests, issues, etc. +- Use instead: You can update objects, like merge requests and issues. + +## foo + +Do not use in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. + ## 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)) +## Geo + +Title case. + ## GitLab -Do not make possessive (GitLab's). This guidance follows [GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). +Do not make possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). -### GitLab.com +## GitLab.com Refers to the GitLab instance managed by GitLab itself. -### GitLab SaaS +## GitLab SaaS Refers to the product license that provides access to GitLab.com. Does not refer to the GitLab instance managed by GitLab itself. -### GitLab self-managed +## GitLab Runner + +Title case. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). + +## GitLab self-managed Refers to the product license for GitLab instances managed by customers themselves. @@ -112,6 +179,7 @@ Refers to the product license for GitLab instances managed by customers themselv When writing about the Guest role: - Use a capital **G**. +- Do not use bold. - Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest role. Instead, write it out. For example, **if you are assigned the Guest role**. - To describe a situation where the Guest role is the minimum required: @@ -128,6 +196,13 @@ Do not use. If the user doesn't find the feature or process to be handy, we lose Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. +## higher + +Do not use when talking about version numbers. + +- Avoid: In GitLab 14.1 and higher. +- Use instead: In GitLab 14.1 and later. + ## I Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) @@ -136,11 +211,52 @@ Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) +## in order to + +Do not use. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) + +## issue + +Lowercase. + +## issue board + +Lowercase. + +## issue weights + +Lowercase. + +## job + +Do not use **build** to be synonymous with **job**. A job is defined in the `.gitlab-ci.yml` file and runs as part of a pipeline. + +If you want to use **CI** with the word **job**, use **CI/CD job** rather than **CI job**. + +## later + +Use when talking about version numbers. + +- Avoid: In GitLab 14.1 and higher. +- Use instead: In GitLab 14.1 and later. + +## log in, log on + +Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. + +## lower + +Do not use when talking about version numbers. + +- Avoid: In GitLab 14.1 and lower. +- Use instead: In GitLab 14.1 and earlier. + ## Maintainer When writing about the Maintainer role: - Use a capital **M**. +- Do not use bold. - Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer role. Instead, write it out. For example, **if you are assigned the Maintainer role**. - To describe a situation where the Maintainer role is the minimum required: @@ -173,11 +289,38 @@ Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale Lowercase. If you use **MR** as the acronym, spell it out on first use. +## milestones + +Lowercase. + +## need to, should + +Try to avoid. If something is required, use **must**. + +- Avoid: You need to set the variable. +- Use instead: You must set the variable. Or: Set the variable. + +**Should** is acceptable for recommended actions or items, or in cases where an event may not +happen. For example: + +- Although you can configure the installation manually, you should use the express configuration to + avoid complications. +- You should see a success message in the console. Contact support if an error message appears + instead. + +## note that + +Do not use. + +- Avoid: Note that you can change the settings. +- Use instead: You can change the settings. + ## Owner When writing about the Owner role: - Use a capital **O**. +- Do not use bold. - Do not use the phrase, **if you are an owner** to mean someone who is assigned the Owner role. Instead, write it out. For example, **if you are assigned the Owner role**. @@ -200,6 +343,7 @@ Do not use. Doing so may negatively affect other users and contributors, which i When writing about the Reporter role: - Use a capital **R**. +- Do not use bold. - Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter role. Instead, write it out. For example, **if you are assigned the Reporter role**. - To describe a situation where the Reporter role is the minimum required: @@ -208,10 +352,18 @@ When writing about the Reporter role: Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. +## Repository Mirroring + +Title case. + ## roles Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +## runner, runners + +Lowercase. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). + ## 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)) @@ -227,6 +379,12 @@ Use **setup** as a noun, and **set up** as a verb. For example: - Your remote office setup is amazing. - To set up your remote office correctly, consider the ergonomics of your work area. +## sign in + +Use instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. + +You can use **single sign-on**. + ## simply, simple Do not use. If the user doesn't find the process to be simple, we lose their trust. @@ -245,17 +403,57 @@ Use instead of **sub-group**. ## that -Do not use. For example: +Do not use when describing a noun. For example: -- Avoid: The file that you save... +- Avoid: The file **that** you save... - Use instead: The file you save... +See also [this, these, that, those](#this-these-that-those). + +## terminal + +Lowercase. For example: + +- Open a terminal. +- From a terminal, run the `docker login` command. + +## there is, there are + +Try to avoid. These phrases hide the subject. + +- Avoid: There are holes in the bucket. +- Use instead: The bucket has holes. + ## 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. +## this, these, that, those + +Always follow these words with a noun. For example: + +- Avoid: **This** improves performance. +- Use instead: **This setting** improves performance. + +- Avoid: **These** are the best. +- Use instead: **These pants** are the best. + +- Avoid: **That** is the one you are looking for. +- Use instead: **That Jedi** is the one you are looking for. + +- Avoid: **Those** need to be configured. +- Use instead: **Those settings** need to be configured. (Or even better, **Configure those settings.**) + +## to-do item + +Use lowercase. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) + +## To-Do List + +Use title case. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) + ## useful Do not use. If the user doesn't find the process to be useful, we lose their trust. @@ -264,6 +462,10 @@ Do not use. If the user doesn't find the process to be useful, we lose their tru Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. +## Value Stream Analytics + +Title case. + ## via 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)) |