Commit 32da8527 authored by Craig Norris's avatar Craig Norris

Merge branch 'docs-aqualls-patch-styleguide' into 'master'

Styleguide fixes and link updates

See merge request gitlab-org/gitlab!49994
parents 64b1e3d3 5a73e24b
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Badge "%s" must be capitalized.' message: 'Badge "%s" must be capitalized.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-badges
level: error level: error
scope: raw scope: raw
raw: raw:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: substitution extends: substitution
message: 'Use the US spelling "%s" instead of the British "%s".' message: 'Use the US spelling "%s" instead of the British "%s".'
link: https://about.gitlab.com/handbook/communication/#top-misused-terms link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
level: error level: error
ignorecase: true ignorecase: true
swap: swap:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Syntax highlighting hint "%s" must be one of: yaml, ruby, plaintext, markdown, javascript, shell, golang, python, dockerfile, or typescript.' message: 'Syntax highlighting hint "%s" must be one of: yaml, ruby, plaintext, markdown, javascript, shell, golang, python, dockerfile, or typescript.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#code-blocks link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#code-blocks
level: error level: error
scope: raw scope: raw
raw: raw:
......
...@@ -8,6 +8,6 @@ extends: existence ...@@ -8,6 +8,6 @@ extends: existence
message: 'Avoid words like "%s" that promise future changes, because documentation is about the current state of the product.' message: 'Avoid words like "%s" that promise future changes, because documentation is about the current state of the product.'
level: suggestion level: suggestion
ignorecase: true ignorecase: true
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#usage-list link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
tokens: tokens:
- currently - currently
...@@ -8,7 +8,7 @@ extends: existence ...@@ -8,7 +8,7 @@ extends: existence
message: '"%s" is a first-person pronoun. Use second- or third-person pronouns (like we, you, us, one) instead.' message: '"%s" is a first-person pronoun. Use second- or third-person pronouns (like we, you, us, one) instead.'
level: warning level: warning
ignorecase: true ignorecase: true
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
tokens: tokens:
- '\bI[ ,;:?!"]|\bI\x27.{1,2}' - '\bI[ ,;:?!"]|\bI\x27.{1,2}'
- me - me
......
...@@ -9,7 +9,7 @@ extends: existence ...@@ -9,7 +9,7 @@ extends: existence
message: 'Avoid using future tense: "%s". Use present tense instead.' message: 'Avoid using future tense: "%s". Use present tense instead.'
ignorecase: true ignorecase: true
level: warning level: warning
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#usage-list link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
raw: raw:
- "(going to( |\n|[[:punct:]])[a-zA-Z]*|" - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
- "will( |\n|[[:punct:]])[a-zA-Z]*|" - "will( |\n|[[:punct:]])[a-zA-Z]*|"
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: substitution extends: substitution
message: 'Use inclusive language. Consider "%s" instead of "%s".' message: 'Use inclusive language. Consider "%s" instead of "%s".'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language
level: suggestion level: suggestion
ignorecase: true ignorecase: true
swap: swap:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: substitution extends: substitution
message: 'Use inclusive language. Consider "%s" instead of "%s".' message: 'Use inclusive language. Consider "%s" instead of "%s".'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language
level: warning level: warning
ignorecase: true ignorecase: true
swap: swap:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: substitution extends: substitution
message: 'Use inclusive language. Consider "%s" instead of "%s".' message: 'Use inclusive language. Consider "%s" instead of "%s".'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language
level: suggestion level: suggestion
ignorecase: true ignorecase: true
swap: swap:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Link "%s" must use the .md file extension.' message: 'Link "%s" must use the .md file extension.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
level: error level: error
scope: raw scope: raw
raw: raw:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Link "%s" must not start with "./".' message: 'Link "%s" must not start with "./".'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
level: error level: error
scope: raw scope: raw
raw: raw:
......
--- ---
# Warning: gitlab.LatinTerms # Warning: gitlab.LatinTerms
# #
# Checks for use of latin terms. # Checks for use of Latin terms.
# #
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: substitution extends: substitution
message: 'Use "%s" instead of "%s", but consider rewriting the sentence.' message: 'Use "%s" instead of "%s", but consider rewriting the sentence.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
level: warning level: warning
nonword: true nonword: true
ignorecase: true ignorecase: true
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Can this reference to "%s" be refactored?' message: 'Can this reference to "%s" be refactored?'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#importance-of-referencing-gitlab-versions-and-tiers link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#gitlab-versions
level: suggestion level: suggestion
nonword: true nonword: true
ignorecase: true ignorecase: true
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Use a comma before the last "and" or "or" in a list of four or more items.' message: 'Use a comma before the last "and" or "or" in a list of four or more items.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation
level: warning level: warning
raw: raw:
- '(?:[\w-_` ]+,){2,}(?:[\w-_` ]+) (and |or )' - '(?:[\w-_` ]+,){2,}(?:[\w-_` ]+) (and |or )'
...@@ -8,7 +8,7 @@ extends: existence ...@@ -8,7 +8,7 @@ extends: existence
message: 'Rewrite "%s" to not use "’s".' message: 'Rewrite "%s" to not use "’s".'
level: warning level: warning
ignorecase: true ignorecase: true
link: https://docs.gitlab.com/ee/development/documentation/styleguide/#contractions link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#contractions
tokens: tokens:
- GitLab's # Straight apostrophe. - GitLab's # Straight apostrophe.
- GitLab’s # Curly closing apostrophe. - GitLab’s # Curly closing apostrophe.
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Link "%s" must be inline.' message: 'Link "%s" must be inline.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#basic-link-criteria link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#basic-link-criteria
level: error level: error
scope: raw scope: raw
raw: raw:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'Link "%s" must be a relative link with a .md extension.' message: 'Link "%s" must be a relative link with a .md extension.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
level: error level: error
scope: raw scope: raw
raw: raw:
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
extends: occurrence extends: occurrence
message: 'Shorter sentences improve readability (max 25 words).' message: 'Shorter sentences improve readability (max 25 words).'
scope: sentence scope: sentence
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
level: warning level: warning
max: 25 max: 25
token: \b(\w+)\b token: \b(\w+)\b
...@@ -9,7 +9,7 @@ ...@@ -9,7 +9,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: '"%s" must contain one and only one space.' message: '"%s" must contain one and only one space.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation
level: error level: error
nonword: true nonword: true
tokens: tokens:
......
...@@ -8,7 +8,7 @@ extends: existence ...@@ -8,7 +8,7 @@ extends: existence
message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.' message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.'
level: suggestion level: suggestion
ignorecase: true ignorecase: true
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#usage-list link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
tokens: tokens:
- easy - easy
- easily - easily
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
# For a list of all options, see https://errata-ai.github.io/vale/styles/ # For a list of all options, see https://errata-ai.github.io/vale/styles/
extends: substitution extends: substitution
message: 'Consider %s instead of "%s".' message: 'Consider %s instead of "%s".'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
level: suggestion level: suggestion
ignorecase: true ignorecase: true
swap: swap:
......
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: substitution extends: substitution
message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.' message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#feature-names link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#feature-names
level: warning level: warning
ignorecase: false ignorecase: false
swap: swap:
......
...@@ -16,7 +16,7 @@ ...@@ -16,7 +16,7 @@
# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
extends: existence extends: existence
message: 'This introduced-in line is not formatted correctly.' message: 'This introduced-in line is not formatted correctly.'
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#text-for-documentation-requiring-version-text link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#version-text-in-the-version-history
level: error level: error
scope: raw scope: raw
raw: raw:
......
...@@ -528,6 +528,7 @@ You can use the following fake tokens as examples: ...@@ -528,6 +528,7 @@ You can use the following fake tokens as examples:
| Usage | Guidance | | Usage | Guidance |
|-----------------------|-----| |-----------------------|-----|
| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. |.
| and/or | Use **or** instead, or another sensible construction. | | and/or | Use **or** instead, or another sensible construction. |
| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. | | currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. |
| easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. | | easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. |
...@@ -539,7 +540,7 @@ You can use the following fake tokens as examples: ...@@ -539,7 +540,7 @@ You can use the following fake tokens as examples:
| i.e. | 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)) | | i.e. | 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)) |
| jargon | Do not use. Define the term or [link to a definition](#links-to-external-documentation). | | jargon | Do not use. Define the term or [link to a definition](#links-to-external-documentation). |
| may, might | **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. | | may, might | **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. |
| me | 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)) | | me, myself, mine | 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)) |
| please | Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). | | please | Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). |
| profanity | Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). | | profanity | Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). |
| 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. | | 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. |
......
...@@ -192,7 +192,7 @@ You can use Vale: ...@@ -192,7 +192,7 @@ You can use Vale:
- [In a Git hook](#configure-pre-push-hooks). Vale only reports errors in the Git hook (the same - [In a Git hook](#configure-pre-push-hooks). Vale only reports errors in the Git hook (the same
configuration as the CI/CD pipelines), and does not report suggestions or warnings. configuration as the CI/CD pipelines), and does not report suggestions or warnings.
#### Vale #### Vale result types
Vale returns three types of results: `suggestion`, `warning`, and `error`: Vale returns three types of results: `suggestion`, `warning`, and `error`:
......
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