Merge branch 'selhorn-vale-readability-update' into 'master'

Updated Vale to use latest Readability extension

See merge request gitlab-org/gitlab!77531

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"

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