We electronically control revisions for this topic and deploy it directly online. Any copies you generate from the latest revision are uncontrolled. Ensure you refer to the latest revision online when possible.
Latest revision: /docs-as-code//2022/11/16/automated-style-checking.html
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.
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)'