Merge branch '208081-docs-test-disabling-vale' into 'master'

Docs: how to turn Vale off and on inside a page

Closes #208081

See merge request gitlab-org/gitlab!25941

doc/development/documentation/index.md

@@ -550,6 +550,24 @@ You can also
 [configure the text editor of your choice](https://errata-ai.github.io/vale/#local-use-by-a-single-writer)
 to display the results.
 
+Vale's test results are not currently displayed in CI, but may be displayed in the future.
+
+##### Disable a Vale test
+
+You can disable a specific Vale linting rule or all Vale linting rules for any portion of a document:
+
+- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag
+  before the text, and a `<!-- vale gitlab.rulename = YES -->` tag after the text,
+  replacing `rulename` with the filename of a test in the [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) directory.
+- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text,
+  and a `<!-- vale on -->` tag after the text.
+
+Whenever possible, exclude only the problematic rule and line(s).
+In some cases, such as list items, you may need to disable linting for the entire
+list until ["Ignore comments are not honored in a Markdown file"](https://github.com/errata-ai/vale/issues/175) is resolved.
+
+For more information, see [Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration).
+
 ## Danger Bot
 
 GitLab uses [Danger](https://github.com/danger/danger) for some elements in

doc/development/documentation/styleguide.md

@@ -308,12 +308,14 @@ tenses, words, and phrases:
     appropriate way.
   - Exceptions to this rule include commonly accepted technical terms, such as
     CI/CD and TCP/IP.
-- We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.,"
+- <!-- vale gitlab.LatinTerms = NO -->
+  We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.,"
   as even native users of English might misunderstand them.
   - Instead of "i.e.," use "that is."
   - Instead of "e.g.," use "for example," "such as," "for instance," or "like."
   - Instead of "etc.," either use "and so on" or consider editing it out, since
     it can be vague.
+    <!-- vale gitlab.rulename = NO -->
 - Avoid using the word *currently* when talking about the product or its
   features. The documentation describes the product as it is, and not as it
   will be at some indeterminate point in the future.
@@ -379,6 +381,8 @@ tenses, words, and phrases:
 | Requests to localhost are not allowed    | Requests to localhost aren't allowed |
 | Specified URL cannot be used             | Specified URL can't be used          |
 
+<!-- vale on -->
+
 ## Text
 
 - [Write in Markdown](#markdown).
@@ -1308,7 +1312,7 @@ a helpful link back to how the feature was developed.
   ```
 
 NOTE: **Note:**
-Version text must be on its own line and surounded by blank lines to render correctly.
+Version text must be on its own line and surrounded by blank lines to render correctly.
 
 ### Versions in the past or future