Automated style checks during release pipeline

Using vale.sh to automatically check content against style sheets and highlight errors - blocking any releases if required.

Using a runner to test and deploy our documentation lets us layer any number of jobs that execute when we update our document. To test for style, we first need to define our test files (see the examples). This could include preset style files or any sort of customized Regex expressions. Once we have setup all our style files, we can instruct our runner to test the document’s content against these files upon every update.

This quickly highlights not only spelling errors, but grammatical, syntax and style errors also. This type of check can take a huge burden off reviewers who generally need to comb through documents with a keen eye. As they are presented in the first place with a mostly clean document.

Of course we still need to review manually, but we have automatically already reduced the number of errors in the document to almost 0.

If we use SVG files for graphics, we can also run the tests on text within these graphics.

Example

An example of a style sheet entry perexpression.yml:

extends: existence
message: |
  In general, use "/[unit]" instead of "p[unit]" in ('%s').
description: |
  This avoids cases where we'd use Gbitps or other wordier units. We should use Gbit
  and not Gb to avoid confusion between GB (gigabyte).
ignorecase: true
level: error
tokens:
  - '([0-9]+\.?\d+[a-z]+ps)'
  - '([0-9]+\.?\d+ [a-z]+ps)'

See also