Automating style checks
A scalable solution to enhance our documentation quality across large and distributed authoring teams.
Using CI/CD pipelines to test and deploy our documentation lets us layer any number of jobs that execute when we update our document.
We can automate style checks and ensure consistency and accuracy by using tools such as Vale.sh. To test for style, we would 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 pipeline to test the document's content against these files upon every update.
Vale.sh Benefits:
- Enforces terminology and syntax.
- Minimizes grammatical and spelling errors.
- Maintains style and voice consistency in collaboration.
- Streamlines the review process.
- Extends to text within SVG files used for graphics.
Example
An example of a style sheet entry perexpression.yml:
extends: existence
message: |
In general, use "/[unit]" instead of "p[unit]" in ('%s').
summary: |
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)'