diff options
Diffstat (limited to 'doc/development/documentation/testing.md')
| -rw-r--r-- | doc/development/documentation/testing.md | 28 |
1 files changed, 26 insertions, 2 deletions
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index ddd44801ae9..2ade6c1e71d 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -224,6 +224,27 @@ guidelines: | UI text from GitLab | Verify it correctly matches the UI, then: If it does not match the UI, update it. If it matches the UI, but the UI seems incorrect, create an issue to see if the UI needs to be fixed. If it matches the UI and seems correct, add it to the [vale spelling exceptions list](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/spelling-exceptions.txt). | | UI text from a third-party product | Rewrite the sentence to avoid it, or [add the vale exception code in-line](#disable-vale-tests). | +#### Vale readability score + +In [`ReadingLevel.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ReadingLevel.yml), +we have implemented +[the Flesch-Kincaid grade level test](https://readable.com/blog/the-flesch-reading-ease-and-flesch-kincaid-grade-level/) +to determine the readability of our documentation. + +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. + ### Install linters At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in @@ -285,11 +306,14 @@ To configure Vale in your editor, install one of the following as appropriate: In the extension's settings: + <!-- vale gitlab.Spelling = NO --> + - Select the **Use CLI** checkbox. - - In the <!-- vale gitlab.Spelling = NO --> **Config** setting, enter an absolute + - In the **Config** setting, enter an absolute path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) in one of the cloned GitLab repositories on your computer. - <!-- vale gitlab.Spelling = YES --> + + <!-- vale gitlab.Spelling = YES --> - In the **Path** setting, enter the absolute path to the Vale binary. In most cases, `vale` should work. To find the location, run `which vale` in a terminal. |