Merge branch 'aqualls-better-vale-messages' into 'master'

Improve messaging on Vale rules

See merge request gitlab-org/gitlab!46608

doc/.vale/gitlab/AlertBoxCaution.yml

@@ -6,6 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 message: "CAUTION: alert boxes must be of the format 'CAUTION: **Caution:**'. 'Caution' can be replaced with 'Warning' or 'Important'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes
 level: warning
 nonword: true
 scope: raw

doc/.vale/gitlab/AlertBoxDanger.yml

@@ -6,6 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 message: "DANGER: alert boxes must be of the format 'DANGER: **Warning:**'. 'Warning' can be replaced with 'Important', 'Deprecated', or 'Required'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes
 level: error
 nonword: true
 scope: raw

doc/.vale/gitlab/AlertBoxNoteTip.yml

@@ -6,6 +6,7 @@
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
 message: "NOTE: and TIP: alert boxes must be of the format 'NOTE: **Note:**' or 'TIP: **Tip:**"
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes
 level: warning
 nonword: true
 scope: raw

doc/.vale/gitlab/CurrentStatus.yml

@@ -5,7 +5,7 @@
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
-message: 'Avoid words like "%s" that promise future changes.'
+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#language-to-avoid

doc/.vale/gitlab/FutureTense.yml

@@ -6,7 +6,7 @@
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
-message: 'Avoid using future tense: "%s"'
+message: 'Avoid using future tense: "%s". Use present tense instead.'
 ignorecase: true
 level: warning
 link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid

doc/.vale/gitlab/RelativeLinks.yml

@@ -5,7 +5,7 @@
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
-message: 'Link "%s" must be relative.'
+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
 level: error
 scope: raw

doc/.vale/gitlab/VersionText.yml

 ---
 # Error: gitlab.VersionText
 #
-# Checks that version text is formatted correctly.
-#
-# Specifically looks for either of the following that is immediately followed on the next line
-# by content, which will break rendering:
-#
-# - `> Introduced` (version text without a link)
-# - `> [Introduced` (version text with a link)
-#
-# Because it excludes `-`, it doesn't look for multi-line version text, for which content
-# immediately on the next line is ok. However, this will often highlight where multi-line version
-# text is attempted without `-` characters.
+# Checks for use of some of the top misused terms at GitLab.
+# For substitutions only flagged as warnings, see SubstitutionWarning.yml
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
-message: '"%s" 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
 level: error
 scope: raw