7 files changed, 34 insertions, 5 deletions
diff --git a/doc/.vale/gitlab/CurrentStatus.yml b/doc/.vale/gitlab/CurrentStatus.yml
index 16a6995843a..040fd3d8a8f 100644
--- a/doc/.vale/gitlab/CurrentStatus.yml
+++ b/doc/.vale/gitlab/CurrentStatus.yml
@@ -5,9 +5,10 @@
 #
 # 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, because documentation is about the current state of the product.'
+message: 'Avoid words like "%s" when you write about future features. Our documentation is about the current state of the product.'
 level: suggestion
 ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/#promising-features-in-future-versions
 tokens:
   - currently
+  - yet
diff --git a/doc/.vale/gitlab/HeadingContent.yml b/doc/.vale/gitlab/HeadingContent.yml
new file mode 100644
index 00000000000..a8dc596f2a2
--- /dev/null
+++ b/doc/.vale/gitlab/HeadingContent.yml
@@ -0,0 +1,18 @@
+---
+# Error: gitlab.HeadingContent
+#
+# Checks for generic, unhelpful subheadings.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: 'Rename the subheading "%s", or re-purpose the content elsewhere.'
+level: warning
+scope: heading
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/#headings-1
+ignorecase: false
+tokens:
+  - How it works
+  - Limitations
+  - Overview
+  - Use cases?
+  - Important notes?
diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml
index 7ee32e41ade..84d1bab3cc6 100644
--- a/doc/.vale/gitlab/SubstitutionWarning.yml
+++ b/doc/.vale/gitlab/SubstitutionWarning.yml
@@ -14,11 +14,12 @@ swap:
   click: select
   code base: codebase
   config: configuration
+  deselect: clear
+  deselected: cleared
   distro: distribution
   file name: filename
   filesystem: file system
   info: information
-  need to: must
   repo: repository
   timezone: time zone
   utilize: use
diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml
index 1cc5a60ac91..a0670d75f18 100644
--- a/doc/.vale/gitlab/Substitutions.yml
+++ b/doc/.vale/gitlab/Substitutions.yml
@@ -13,6 +13,7 @@ ignorecase: true
 swap:
   codequality: code quality
   Customer [Pp]ortal: Customers Portal
+  disallow: prevent
   frontmatter: front matter
   GitLabber: GitLab team member
   GitLabbers: GitLab team members
diff --git a/doc/.vale/gitlab/Uppercase.yml b/doc/.vale/gitlab/Uppercase.yml
index c9021dc862e..f1b06e10fe6 100644
--- a/doc/.vale/gitlab/Uppercase.yml
+++ b/doc/.vale/gitlab/Uppercase.yml
@@ -51,6 +51,7 @@ exceptions:
   - EKS
   - ELB
   - EOL
+  - EWM
   - EXIF
   - FAQ
   - FIDO
@@ -144,6 +145,7 @@ exceptions:
   - RSA
   - RDS
   - RSS
+  - RTC
   - RVM
   - SAAS
   - SAML
@@ -171,6 +173,7 @@ exceptions:
   - SSH
   - SSL
   - SSO
+  - STI
   - SVG
   - SVN
   - TCP
diff --git a/doc/.vale/gitlab/Wordy.yml b/doc/.vale/gitlab/Wordy.yml
index 7818ecbb74a..716fdc6c38d 100644
--- a/doc/.vale/gitlab/Wordy.yml
+++ b/doc/.vale/gitlab/Wordy.yml
@@ -5,9 +5,12 @@
 #
 # For a list of all options, see https://docs.errata.ai/vale/styles
 extends: substitution
-message: 'Be concise: "%s" is less wordy than "%s".'
+message: '%s "%s".'
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 level: suggestion
 ignorecase: true
 swap:
-  in order to: to
+  in order to: "Be concise: use 'to' rather than"
+  needs? to: "Rewrite the sentence, or use 'must', instead of"
+  note that: "Be concise: rewrite the sentence to not use"
+  please: "Remove this word from the sentence: "
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt
index 98254c2259b..6dc0704963b 100644
--- a/doc/.vale/gitlab/spelling-exceptions.txt
+++ b/doc/.vale/gitlab/spelling-exceptions.txt
@@ -229,6 +229,7 @@ Gemfile
 Gemnasium
 Gemojione
 Getter
+getters
 Getters
 gettext
 Git
@@ -576,6 +577,7 @@ sharded
 sharding
 shfmt
 Shibboleth
+Shimo
 Shopify
 Sidekiq
 Silverlight