Merge branch 'selhorn-move-words-to-wordlist' into 'master'

Docs style guide: move words to wordlist

See merge request gitlab-org/gitlab!66761

doc/development/documentation/styleguide/index.md

@@ -292,16 +292,11 @@ Do not include the same information in multiple places.
 
 ## Language
 
-GitLab documentation should be clear and easy to understand. Avoid unnecessary words.
+GitLab documentation should be clear and easy to understand.
 
+- Avoid unnecessary words.
 - 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).)
-- Rewrite to avoid wordiness:
-  - there is
-  - there are
-  - enables you to
-  - in order to
-  - because of the fact that
 
 ### Capitalization
 
@@ -324,28 +319,13 @@ create an issue or an MR to propose a change to the user interface text.
 
 #### Feature names
 
-- *Feature names are typically lowercase*, like those describing actions and
-  types of objects in GitLab. For example:
-  - epics
-  - issues
-  - issue weights
-  - merge requests
-  - milestones
-  - reorder issues
-  - runner, runners, shared runners
-  - a to-do item (tested in [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml))
+- *Feature names are typically lowercase*.
 - *Some features are capitalized*, typically nouns naming GitLab-specific
-  capabilities or tools. For example:
-  - GitLab CI/CD
-  - Repository Mirroring
-  - Value Stream Analytics
-  - the To-Do List
-  - the Web IDE
-  - Geo
-  - GitLab Runner (see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529) for details)
-
-Document any exceptions in this style guide. If you're not sure, ask a GitLab
-Technical Writer so that they can help decide and document the result.
+  capabilities or tools.
+  
+See the [word list](word_list.md) for details.
+
+If the term is not in the word list, ask a GitLab Technical Writer for advice.
 
 Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/)
 or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml)
@@ -366,16 +346,6 @@ Follow the capitalization style listed at the authoritative source
 for the entity, which may use non-standard case styles. For example: GitLab and
 npm.
 
-Use forms of *sign in*, instead of *log in* or *login*. For example:
-
-- Sign in to GitLab.
-- Open the sign-in page.
-
-Exceptions to this rule include the concept of *single sign-on* and
-references to user interface elements. For example:
-
-- To sign in to product X, enter your credentials, and then select **Log in**.
-
 ### Fake user information
 
 You may need to include user information in entries such as a REST call or user profile.

doc/development/documentation/styleguide/word_list.md

@@ -47,6 +47,10 @@ Try to avoid extra words when referring to an example or table in a documentatio
 
 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))
 
+## 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))
@@ -86,6 +90,10 @@ 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.
+
 ## etc.
 
 Try to avoid. Be as specific as you can. Do not use **and so on** as a replacement.
@@ -97,20 +105,28 @@ Try to avoid. Be as specific as you can. Do not use **and so on** as a replaceme
 
 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).
 
-### 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.
 
@@ -143,6 +159,22 @@ 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.
+
+## issue
+
+Lowercase.
+
+## issue weights
+
+Lowercase.
+
+## log in, log on
+
+Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it.
+
 ## Maintainer
 
 When writing about the Maintainer role:
@@ -180,6 +212,10 @@ 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.
+
 ## Owner
 
 When writing about the Owner role:
@@ -215,10 +251,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))
@@ -234,6 +278,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.
@@ -257,12 +307,27 @@ Do not use. For example:
 - Avoid: The file that you save...
 - Use instead: The file you save...
 
+## 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.
 
+## 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.
@@ -271,6 +336,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))