1 files changed, 22 insertions, 5 deletions
diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml
index 8d6c18c1520..383ae38da16 100644
--- a/doc/.vale/gitlab/SubstitutionWarning.yml
+++ b/doc/.vale/gitlab/SubstitutionWarning.yml
@@ -1,16 +1,18 @@
 ---
 # Warning: gitlab.SubstitutionWarning
 #
-# 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.
+# Checks for misused terms or common shorthand that should not be used at GitLab, but can't be flagged as errors.
+# Substitutions.yml also exists.
 #
 # For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: "If possible, use %s instead of '%s'."
-link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+message: "Use '%s' instead of '%s' when possible."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 level: warning
 ignorecase: true
 swap:
+  active user: "billable user"
+  active users: "billable users"
   air(?:-| )?gapped: "offline environment"
   bullet: "list item"
   click: "select"
@@ -19,11 +21,26 @@ swap:
   deselect: "clear"
   deselected: "cleared"
   distro: "distribution"
+  docs: "documentation"
+  e-mail: "email"
+  ex: "for example"
   file name: "filename"
   filesystem: "file system"
-  GFM: "'GitLab Flavored Markdown' or 'GitHub Flavored Markdown'"
+  GLFM: "GitLab Flavored Markdown"
+  GFM: "GitLab Flavored Markdown' or 'GitHub Flavored Markdown"
   info: "information"
+  it is recommended: "you should"
   n/a: "not applicable"
+  navigate to: "go to"
+  OAuth2: "OAuth 2.0"
+  once that: "after that"
+  once the: "after the"
+  once you: "after you"
   repo: "repository"
+  since: "because' or 'after"
+  sub-group: "subgroup"
+  sub-groups: "subgroups"
   timezone: "time zone"
   utilize: "use"
+  we recommend: "you should"
+  within: "in"