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

Styleguide fixes and link updates

See merge request gitlab-org/gitlab!49994

doc/.vale/gitlab/BadgeCapitalization.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/.vale/gitlab/British.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 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
 ignorecase: true
 swap:

doc/.vale/gitlab/CodeblockFences.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/.vale/gitlab/CurrentStatus.yml

@@ -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.'
 level: suggestion
 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:
   - currently

doc/.vale/gitlab/FirstPerson.yml

@@ -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.'
 level: warning
 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:
   - '\bI[ ,;:?!"]|\bI\x27.{1,2}'
   - me

doc/.vale/gitlab/FutureTense.yml

@@ -9,7 +9,7 @@ extends: existence
 message: 'Avoid using future tense: "%s". Use present tense instead.'
 ignorecase: true
 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:
   - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
   - "will( |\n|[[:punct:]])[a-zA-Z]*|"

doc/.vale/gitlab/InclusionAbleism.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 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
 ignorecase: true
 swap:

doc/.vale/gitlab/InclusionCultural.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 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
 ignorecase: true
 swap:

doc/.vale/gitlab/InclusionGender.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 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
 ignorecase: true
 swap:

doc/.vale/gitlab/InternalLinkExtension.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/.vale/gitlab/InternalLinkFormat.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/.vale/gitlab/LatinTerms.yml

 ---
 # 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
 extends: substitution
 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
 nonword: true
 ignorecase: true

doc/.vale/gitlab/OutdatedVersions.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 nonword: true
 ignorecase: true

doc/.vale/gitlab/OxfordComma.yml

@@ -7,7 +7,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 raw:
   - '(?:[\w-_` ]+,){2,}(?:[\w-_` ]+) (and |or )'

doc/.vale/gitlab/Possessive.yml

@@ -8,7 +8,7 @@ extends: existence
 message: 'Rewrite "%s" to not use "’s".'
 level: warning
 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:
   - GitLab's  # Straight apostrophe.
   - GitLab’s  # Curly closing apostrophe.

doc/.vale/gitlab/ReferenceLinks.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/.vale/gitlab/RelativeLinks.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/.vale/gitlab/SentenceLength.yml

@@ -7,7 +7,7 @@
 extends: occurrence
 message: 'Shorter sentences improve readability (max 25 words).'
 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
 max: 25
 token: \b(\w+)\b

doc/.vale/gitlab/SentenceSpacing.yml

@@ -9,7 +9,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 nonword: true
 tokens:

doc/.vale/gitlab/Simplicity.yml

@@ -8,7 +8,7 @@ extends: existence
 message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.'
 level: suggestion
 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:
   - easy
   - easily

doc/.vale/gitlab/SubstitutionSuggestions.yml

@@ -7,7 +7,7 @@
 # For a list of all options, see https://errata-ai.github.io/vale/styles/
 extends: substitution
 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
 ignorecase: true
 swap:

doc/.vale/gitlab/ToDo.yml

@@ -6,7 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 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
 ignorecase: false
 swap:

doc/.vale/gitlab/VersionText.yml

@@ -16,7 +16,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 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
 scope: raw
 raw:

doc/development/documentation/styleguide/index.md

@@ -528,6 +528,7 @@ You can use the following fake tokens as examples:
 
 | Usage | Guidance |
 |-----------------------|-----|
+| admin, admin area     | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. |.
 | 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. |
 | 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:
 | 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). |
 | 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). |
 | 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. |

doc/development/documentation/testing.md

@@ -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
   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`: