From d21064683f0e6da1ffc46c855c5bbc8a28501c10 Mon Sep 17 00:00:00 2001
From: Suzanne Selhorn <sselhorn@gitlab.com>
Date: Wed, 5 Jan 2022 21:09:20 +0000
Subject: [PATCH] Updated Vale to use latest Readability extension

---
 doc/.vale/gitlab/ReadingLevel.yml        | 12 ++++++------
 doc/development/documentation/testing.md | 11 ++---------
 2 files changed, 8 insertions(+), 15 deletions(-)

diff --git a/doc/.vale/gitlab/ReadingLevel.yml b/doc/.vale/gitlab/ReadingLevel.yml
index 2e78c3ef36cdd..cd7597ee8dc51 100644
--- a/doc/.vale/gitlab/ReadingLevel.yml
+++ b/doc/.vale/gitlab/ReadingLevel.yml
@@ -3,11 +3,11 @@
 #
 # Checks the Flesch-Kincaid reading level.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: readability
-message: "Grade level (%s) is high. To lower the score, use shorter sentences and words."
+# https://docs.errata.ai/vale/styles#metric
+extends: metric
+message: "The grade level - %s - refers to how hard the content is to understand. Aim for 8th grade or lower by using shorter sentences and words."
 link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-readability-score
 level: suggestion
-grade: 8
-metrics:
-  - Flesch-Kincaid
+formula: |
+  (0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59
+condition: "> 1"
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index 13648a7c7108b..134183a0e75b1 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -234,15 +234,8 @@ As a general guideline, the lower the score, the more readable the documentation
 For example, a page that scores `12` before a set of changes, and `9` after, indicates an iterative improvement to readability. The score is not an exact science, but is meant to help indicate the
 general complexity level of the page.
 
-The readability score is calculated by using the following formula:
-
-```plaintext
-(.39 x ASL) + (11.8 x ASW) – 15.59
-```
-
-- `ASL` is average sentence length (the number of words divided by the number of sentences).
-- `ASW` is the average number of syllables per word (the number of syllables divided by the number of words).
-- The score excludes headings, code blocks, and lists.
+The readability score is calculated based on the number of words per sentence, and the number
+of syllables per word. For more information, see [the Vale documentation](https://docs.errata.ai/vale/styles#metric).
 
 ### Install linters
 
-- 
GitLab