Merge branch 'docs-aqualls-tidy-rule-comments' into 'master'

Update Vale test comments for search results

See merge request gitlab-org/gitlab!50896

doc/.vale/gitlab/Admin.yml

 ---
 # Warning: gitlab.Admin
 #
-# You should not use "admin", but "Admin Area" is OK.
+# Checks for "admin" and recommends using the full word instead. "Admin Area" is OK.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution

doc/.vale/gitlab/AlertBoxStyle.yml

 ---
 # Error: gitlab.AlertBoxStyle
 #
-# Makes sure alert boxes are used with block quotes.
+# Makes sure alert boxes are used with block quotes. Checks for 3 formatting issues:
 #
-# Checks for 3 formatting issues:
 # - Alert boxes inside a block quote (">")
 # - Alert boxes with the note text on the same line
 # - Alert boxes using words other than "NOTE" or "WARNING"

doc/.vale/gitlab/British.yml

 ---
 # Error: gitlab.British
 #
-# Checks that US spelling is used over British spelling.
+# Checks that US spelling is used instead of British spelling.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution

doc/.vale/gitlab/CurlStringsQuoted.yml

 ---
 # Error: gitlab.CurlStringsQuoted
 #
-# Ensures all code blocks using curl quote any URL strings.
+# Ensures all code blocks using `curl` wrap URL strings in quotation marks.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence

doc/.vale/gitlab/FutureTense.yml

 ---
 # Suggestion: gitlab.FutureTense
 #
-# Checks for use of future tense in sentences. Present tense is preferred as
-# much as possible.
+# Checks for use of future tense in sentences. Present tense is strongly preferred.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence

doc/.vale/gitlab/OxfordComma.yml

 ---
 # Warning: gitlab.OxfordComma
 #
-# Checks for the lack of an Oxford comma. In some cases, will catch overly
-# complex sentence structures with lots of commas.
+# Checks for the lack of an Oxford comma. In some cases, will catch overly complex sentence structures with lots of commas.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence

doc/.vale/gitlab/ReferenceLinks.yml

 ---
 # Error: gitlab.ReferenceLinks
 #
-# Checks for the presence of reference-style links that must be inline.
+# Checks for reference-style links that should be converted to inline links.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence

doc/.vale/gitlab/SentenceSpacing.yml

 ---
 # Error: gitlab.SentenceSpacing
 #
-# Checks for the following in common content scenarios:
-#
-# - No spaces.
-# - More than one space.
+# Checks for incorrect spacing (no spaces, or more than one space) around punctuation.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence

doc/.vale/gitlab/Spelling.yml

 ---
 # Warning: gitlab.Spelling
 #
-# Checks for possible spelling mistakes in content, not code. May find false positives
-# due to links using angle brackets: <https://example.com>. These can be ignored.
+# Checks for possible spelling mistakes in content, not code. Results from links using angle brackets (<https://example.com>) should be corrected.
 #
 # If a word is flagged as a spelling mistake incorrectly, such as a product name,
 # you can submit an MR to update `spelling-exceptions.txt` with the missing word.

doc/.vale/gitlab/SubstitutionSuggestions.yml

 ---
 # Suggestion: gitlab.SubstitutionSuggestions
 #
-# Suggests better options for frequently misused terms at GitLab that are
-# often - but not always - incorrect.
+# Suggests better options for frequently misused terms that are often - but not always - incorrect.
+# SubstitutionWarning.yml and Substitutions.yml also exist.
 #
 # For a list of all options, see https://errata-ai.github.io/vale/styles/
 extends: substitution

doc/.vale/gitlab/SubstitutionWarning.yml

 ---
 # Warning: gitlab.SubstitutionWarning
 #
-# Warns against using common shorthand for terms.
-# For substitutions flagged as errors, see Substitutions.yml
+# Checks for misused terms or common shorthand that should never be used at GitLab, but can't be flagged as errors.
+# Substitutions.yml and SubstitionSuggestions.yml also exist.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution

doc/.vale/gitlab/Substitutions.yml

 ---
 # Error: gitlab.Substitutions
 #
-# Checks for use of some of the top misused terms at GitLab.
-# For substitutions only flagged as warnings, see SubstitutionWarning.yml
+# Checks for misused terms that should never be used at GitLab.
+# SubstitutionWarning.yml and SubstitionSuggestions.yml also exist.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution