diff options
Diffstat (limited to 'doc/development/documentation/styleguide/word_list.md')
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 311 |
1 files changed, 246 insertions, 65 deletions
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 595dab09bf5..9c375379685 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -5,9 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- -# A-Z word list +# Recommended word list -To help ensure consistency in the documentation, follow this guidance. +To help ensure consistency in the documentation, the Technical Writing team +recommends these wording choices. The GitLab handbook also maintains a list of +[top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/). For guidance not on this page, we defer to these style guides: @@ -20,7 +22,7 @@ For guidance not on this page, we defer to these style guides: ## `@mention` Try to avoid **`@mention`**. Say **mention** instead, and consider linking to the -[mentions topic](../../../user/project/issues/issue_data_and_actions.md#mentions). +[mentions topic](../../../user/discussions/index.md#mentions). Don't use backticks. ## above @@ -31,9 +33,14 @@ Try to avoid using **above** when referring to an example or table in a document Do not use **above** when referring to versions of the product. Use [**later**](#later) instead. -- Do: In GitLab 14.4 and later... -- Do not: In GitLab 14.4 and above... -- Do not: In GitLab 14.4 and higher... +Use: + +- In GitLab 14.4 and later... + +Instead of: + +- In GitLab 14.4 and above... +- In GitLab 14.4 and higher... ## access level @@ -47,16 +54,21 @@ Capitalize these words when you refer to the UI. Otherwise use lowercase. Use **administrator** instead of **admin** when talking about a user's access level. Use lowercase unless you are referring to the **Admin** access level you select in the UI. -To view the administrator access type, in the GitLab UI, go to the Admin Area and select +To view the administrator access level, in the GitLab UI, go to the Admin Area and select **Users**. Then select **New user**.  An **administrator** is not a [role](#roles) or [permission](#permissions). -- Do: To do this thing, you must be an administrator. -- Do: To do this thing, you must have the administrator access level. -- Do not: To do this thing, you must have the Admin role. +Use: + +- To do this thing, you must be an administrator. +- To do this thing, you must have the administrator access level. + +Instead of: + +- To do this thing, you must have the Admin role. ## Admin Area @@ -65,10 +77,16 @@ This area of the UI says **Admin Area** at the top of the page and on the menu. ## allow, enable -Try to avoid **allow** and **enable**, unless you are talking about security-related features. For example: +Try to avoid **allow** and **enable**, unless you are talking about security-related features. -- Do: Use this feature to create a pipeline. -- Do not: This feature allows you to create a pipeline. +Use: + +- You can add a file to your repository. + +Instead of: + +- This feature allows you to add a file to your repository. +- This feature enables users to add files to their repository. 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). @@ -124,8 +142,13 @@ Use **text box** to refer to the UI field. Do not use **field** or **box**. For Don't use a descriptor with **button**. -- Do: Select **Run pipelines**. -- Do not: Select the **Run pipelines** button. +Use: + +- Select **Run pipelines**. + +Instead of: + +- Select the **Run pipelines** button. ## cannot, can not @@ -148,6 +171,13 @@ If you must refer to the checkbox, you can say it is selected or cleared. For ex - Ensure the **Protect environment** checkbox is cleared. - Ensure the **Protect environment** checkbox is selected. +## checkout, check out + +Use **check out** as a verb. For the Git command, use `checkout`. + +- Use `git checkout` to check out a branch locally. +- Check out the files you want to edit. + ## CI/CD CI/CD is always uppercase. No need to spell it out on first use. @@ -185,8 +215,8 @@ When writing about the Developer role: - 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: - - Do: at least the Developer role - - Do not: the Developer role or higher + - Use: at least the Developer role + - Instead of: the Developer role or higher Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. @@ -208,8 +238,13 @@ For example: Use **earlier** when talking about version numbers. -- Do: In GitLab 14.1 and earlier. -- Do not: In GitLab 14.1 and lower. +Use: + +- In GitLab 14.1 and earlier. + +Instead of: + +- In GitLab 14.1 and lower. ## easily @@ -245,8 +280,13 @@ Use lowercase for **epic board**. Try to avoid **etc.**. Be as specific as you can. Do not use [**and so on**](#and-so-on) as a replacement. -- Do: You can update objects, like merge requests and issues. -- Do not: You can update objects, like merge requests, issues, etc. +Use: + +- You can update objects, like merge requests and issues. + +Instead of: + +- You can update objects, like merge requests, issues, etc. ## expand @@ -256,8 +296,13 @@ Use **expand** instead of **open** when you are talking about expanding or colla Use **box** instead of **field** or **text box**. -- Do: In the **Variable name** box, enter `my text`. -- Do not: In the **Variable name** field, enter `my text`. +Use: + +- In the **Variable name** box, enter `my text`. + +Instead of: + +- In the **Variable name** field, enter `my text`. However, you can make an exception when you are writing a task and you need to refer to all of the fields at once. For example: @@ -311,8 +356,8 @@ When writing about the Guest role: - 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: - - Do: at least the Guest role - - Do not: the Guest role or higher + - Use: at least the Guest role + - Instead of: the Guest role or higher Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. @@ -328,16 +373,26 @@ Do not use **high availability** or **HA**. Instead, direct readers to the GitLa Do not use **higher** when talking about version numbers. -- Do: In GitLab 14.4 and later... -- Do not: In GitLab 14.4 and higher... -- Do not: In GitLab 14.4 and above... +Use: + +- In GitLab 14.4 and later... + +Instead of: + +- In GitLab 14.4 and higher... +- In GitLab 14.4 and above... ## hit Don't use **hit** to mean **press**. -- Do: Press **ENTER**. -- Do not: Hit the **ENTER** button. +Use: + +- Press **ENTER**. + +Instead of: + +- Hit the **ENTER** button. ## I @@ -369,13 +424,31 @@ Do not use **build** to be synonymous with **job**. A job is defined in the `.gi If you want to use **CI** with the word **job**, use **CI/CD job** rather than **CI job**. +## Kubernetes executor + +GitLab Runner can run jobs on a Kubernetes cluster. To do this, GitLab Runner uses the Kubernetes executor. + +When referring to this feature, use: + +- Kubernetes executor for GitLab Runner +- Kubernetes executor + +Do not use: + +- GitLab Runner Kubernetes executor, because this can infringe on the Kubernetes trademark. + ## later Use **later** when talking about version numbers. -- Do: In GitLab 14.1 and later... -- Do not: In GitLab 14.1 and higher... -- Do not: In GitLab 14.1 and above... +Use: + +- In GitLab 14.1 and later... + +Instead of: + +- In GitLab 14.1 and higher... +- In GitLab 14.1 and above... ## list @@ -390,8 +463,13 @@ Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the use Do not use **lower** when talking about version numbers. -- Do: In GitLab 14.1 and earlier. -- Do not: In GitLab 14.1 and lower. +Use: + +- In GitLab 14.1 and earlier. + +Instead of: + +- In GitLab 14.1 and lower. ## Maintainer @@ -402,8 +480,8 @@ When writing about the Maintainer role: - 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: - - Do: at least the Maintainer role - - Do not: the Maintainer role or higher + - Use: at least the Maintainer role + - Instead of: the Maintainer role or higher Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. @@ -446,8 +524,14 @@ Do not use **navigate**. Use **go** instead. For example: Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. -- Do: You must set the variable. Or: Set the variable. -- Do not: You need to set the variable. +Use: + +- You must set the variable. +- Set the variable. + +Instead of: + +- You need to set the variable. **Should** is acceptable for recommended actions or items, or in cases where an event may not happen. For example: @@ -461,22 +545,63 @@ happen. For example: Do not use **note that** because it's wordy. -- Do: You can change the settings. -- Do not: Note that you can change the settings. +Use: + +- You can change the settings. + +Instead of: + +- Note that you can change the settings. ## on When documenting how to select high-level UI elements, use the word **on**. -- Do: `On the left sidebar...` +Use: + +- `On the left sidebar...` + +Instead of: + - Do not: `From the left sidebar...` or `In the left sidebar...` ## once The word **once** means **one time**. Don't use it to mean **after** or **when**. -- Do: When the process is complete... -- Do not: Once the process is complete... +Use: + +- When the process is complete... + +Instead of: + +- Once the process is complete... + +## only + +Put the word **only** next to the word it modifies. + +- You can create only private projects. + +In this example, **only** modifies the noun **projects**. The sentence means you can create one type of project--a private project. + +- You can only create private projects. + +In this example, **only** modifies the verb **create**. This sentence means that you can't perform other actions, +like deleting private projects, or adding users to them. + +## override + +Use **override** to indicate temporary replacement. + +For example, a value might be overridden when a job runs. The +original value does not change. + +## overwrite + +Use **overwrite** to indicate permanent replacement. + +For example, a log file might overwrite a log file of the same name. ## Owner @@ -518,8 +643,8 @@ When writing about the Reporter role: - 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: - - Do: at least the Reporter role - - Do not: the Reporter role or higher + - Use: at least the Reporter role + - Instead of: the Reporter role or higher Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. @@ -541,8 +666,13 @@ Use lowercase for **runners**. These are the agents that run CI/CD jobs. See als Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: -- Do: Select the jobs you want. -- Do not: Select the job(s) you want. +Use: + +- Select the jobs you want. + +Instead of: + +- Select the job(s) you want. If you can select multiples of something, then write the word as plural. @@ -564,7 +694,12 @@ into separate areas, refer to these areas as sections. We often think of expandable/collapsible areas as **sections**. When you refer to expanding or collapsing a section, don't include the word **section**. -- Do: Expand **Auto DevOps**. +Use: + +- Expand **Auto DevOps**. + +Instead of: + - Do not: Expand the **Auto DevOps** section. ## select @@ -597,8 +732,13 @@ Do not use **simply** or **simple**. If the user doesn't find the process to be The word **since** indicates a timeframe. For example, **Since 1984, Bon Jovi has existed**. Don't use **since** to mean **because**. -- Do: Because you have the Developer role, you can delete the widget. -- Do not: Since you have the Developer role, you can delete the widget. +Use: + +- Because you have the Developer role, you can delete the widget. + +Instead of: + +- Since you have the Developer role, you can delete the widget. ## slashes @@ -616,8 +756,13 @@ Use **subgroup** (no hyphen) instead of **sub-group**. ([Vale](../testing.md#val Do not use **that** when describing a noun. For example: -- Do: The file you save... -- Do not: The file **that** you save... +Use: + +- The file you save... + +Instead of: + +- The file **that** you save... See also [this, these, that, those](#this-these-that-those). @@ -636,8 +781,13 @@ Use **text box** instead of **field** or **box** when referring to the UI elemen Try to avoid **there is** and **there are**. These phrases hide the subject. -- Do: The bucket has holes. -- Do not: There are holes in the bucket. +Use: + +- The bucket has holes. + +Instead of: + +- There are holes in the bucket. ## they @@ -649,17 +799,17 @@ a gender-neutral pronoun. Always follow these words with a noun. For example: -- Do: **This setting** improves performance. -- Do not: **This** improves performance. +- Use: **This setting** improves performance. +- Instead of: **This** improves performance. -- Do: **These pants** are the best. -- Do not: **These** are the best. +- Use: **These pants** are the best. +- Instead of: **These** are the best. -- Do: **That droid** is the one you are looking for. -- Do not: **That** is the one you are looking for. +- Use: **That droid** is the one you are looking for. +- Instead of: **That** is the one you are looking for. -- Do: **Those settings** need to be configured. (Or even better, **Configure those settings.**) -- Do not: **Those** need to be configured. +- Use: **Those settings** need to be configured. (Or even better, **Configure those settings.**) +- Instead of: **Those** need to be configured. ## to-do item @@ -683,6 +833,19 @@ 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. + +Use: + +- You can configure a pipeline. + +Instead of: + +- 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. @@ -700,8 +863,13 @@ Do not use Latin abbreviations. Use **with**, **through**, or **by using** inste Try to avoid **we** and focus instead on how the user can accomplish something in GitLab. -- Do: Use widgets when you have work you want to organize. -- Do not: We created a feature for you to add widgets. +Use: + +- Use widgets when you have work you want to organize. + +Instead of: + +- We created a feature for you to add widgets. One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) @@ -709,5 +877,18 @@ 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. + +Use: + +- You can configure a pipeline. + +Instead of: + +- Users can configure a pipeline. + <!-- vale on --> <!-- markdownlint-enable --> |