diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index 7b20887f53fb3ccb598c28a66be18a8a7067f2da..f08d457134d7cd21628d44adfc502c1b9a3243c1 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -12,6 +12,7 @@ level: warning ignorecase: true swap: air(?:-| )?gapped: offline environment + bullet: list item click: select code base: codebase config: configuration diff --git a/doc/development/backend/ruby_style_guide.md b/doc/development/backend/ruby_style_guide.md index 5202ba0baa55acc692c09e6dedac2480e697c89b..6c8125a6157aaeed5bbcc83e19bdf271efe9d9f6 100644 --- a/doc/development/backend/ruby_style_guide.md +++ b/doc/development/backend/ruby_style_guide.md @@ -13,7 +13,7 @@ Generally, if a style is not covered by [existing Rubocop rules or style guides] Before adding a new cop to enforce a given style, make sure to discuss it with your team. When the style is approved by a backend EM or by a BE staff eng, add a new section to this page to document the new rule. For every new guideline, add it in a new section and link the discussion from the section's -[version history note](../documentation/versions.md#add-a-version-history-bullet) +[version history note](../documentation/versions.md#add-a-version-history-item) to provide context and serve as a reference. Just because something is listed here does not mean it cannot be reopened for discussion. diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 37e58f1ec7aaf1f51beb2b35f1de18081512aecc..ce18a70badc0eeaf619e5f6889be2e549ad89bc3 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -75,7 +75,7 @@ Example response: ``` ```` -Adjust the [version history note accordingly](versions.md#add-a-version-history-bullet) +Adjust the [version history note accordingly](versions.md#add-a-version-history-item) to describe the GitLab release that introduced the API call. ## Method description diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 21368098f39b99990b5bcd0f21e89084d9bcc85e..bba8e99260d9008177cf3020c26c992feddc079e 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -237,7 +237,7 @@ consider using subsections for each distinct task. ### Related topics If inline links are not sufficient, you can create a topic called **Related topics** -and include a bulleted list of related topics. This topic should be above the Troubleshooting section. +and include an unordered list of related topics. This topic should be above the Troubleshooting section. ```markdown # Related topics diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 72031642eb7b0dbb4a2a061d4fdee4cbee6d5f20..5db09d4263e64f192762ab931fa0b8b67f3270c0 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -980,7 +980,7 @@ If you are documenting multiple fields and only one field needs explanation, do 1. Expand **Push rules**. 1. Complete the fields. **Branch name** must be a regular expression. -To describe multiple fields, use bullets: +To describe multiple fields, use unordered list items: 1. Expand **General pipelines**. 1. Complete the fields. diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 0affc11de0272f2aeab74ac04bbdf56482ca571f..06440ab904f46ff016c7b09f42b6f9a1757f66b0 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -166,6 +166,14 @@ Use **text box** to refer to the UI field. Do not use **field** or **box**. For - In the **Variable name** text box, enter a value. + +## bullet + +Don't refer to individual items in an ordered or unordered list as **bullets**. Use **list item** instead. If you need to be less ambiguous, you can use: + +- **Ordered list item** for items in an ordered list. +- **Unordered list item** for items in an unordered list. + ## button Don't use a descriptor with **button**. diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 7d88875ccf24064aff6a892894fc8ebac7def6bd..106567e6d3fe1a5ccc45b92fe6d92f0c401b18e2 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -29,9 +29,9 @@ either as a **Version history** bullet or as an inline text reference. You do not need to add version information on the pages in the `/development` directory. -### Add a **Version history** bullet +### Add a **Version history** item -If all content in a topic is related, add a version history bullet after the topic heading. +If all content in a topic is related, add a version history item after the topic heading. For example: ```markdown @@ -42,7 +42,7 @@ For example: This feature does something. ``` -The bullet text must include these words in order. Capitalization doesn't matter. +The item text must include these words in order. Capitalization doesn't matter. - `introduced`, `enabled`, `deprecated`, `changed`, `moved`, `recommended`, `removed`, or `renamed` - `in` or `to` @@ -122,7 +122,7 @@ The title and a removed indicator remains until three months after the removal. To remove a page: -1. Leave the page title. Remove all other content, including the version history bullets and the word `WARNING:`. +1. Leave the page title. Remove all other content, including the version history items and the word `WARNING:`. 1. After the title, change `(deprecated)` to `(removed)`. 1. Update the YAML metadata: - For `remove_date`, set the value to a date three months after @@ -156,7 +156,7 @@ This content is removed from the documentation as part of the Technical Writing To remove a topic: 1. Leave the title and the details of the deprecation and removal. Remove all other content, - including the version history bullets and the word `WARNING:`. + including the version history items and the word `WARNING:`. 1. Add `(removed)` after the title. 1. Add the following HTML comments above and below the topic. For the `remove_date`, set a date three months after the release where it was removed. @@ -184,7 +184,7 @@ GitLab 14.0, 13.0 and 12.0 are supported. [View the list of supported versions](https://about.gitlab.com/support/statement-of-support.html#version-support). -If you see version history bullets or inline text that refers to unsupported versions, you can remove it. +If you see version history items or inline text that refers to unsupported versions, you can remove it. Historical feature information is available in [release posts](https://about.gitlab.com/releases/) or by searching for the issue or merge request where the work was done.