Implement Vale as a syntax-aware linter for docs
Problem to solve
Many GitLab authors draft documentation without a knowledge of GitLab documentation style, readability, and grammar guidelines. For many authors, English is not the first language, and documentation is not a core skill.
As a result, GitLab technical writers spend significant time harmonizing draft documentation with GitLab standards.
Further details
As this problem is not unique to GitLab, others have addressed the problem with linters. Perhaps the most code-friendly linter of this kind today is Vale.
The people behind the testthedocs project have collected Vale OSS style templates from a number of organizations in the noted repository.
While there is some overlap with markdownlint
, we expect Vale to work "hand-in-hand" as a customizable linter focused on language syntax and grammar.
Proposal
Set up our documentation repositories with Vale. With IDE plugins, Vale can highlight selected syntax and grammar issues for writers before they commit content to our repositories.
Create rules that match the requirements of the GitLab documentation style guide, as closely as possible.
Implement desired rules on all GitLab repositories with published documentation. Add instructions for how writers (Technical Writers, Developers, and others) can take advantage, by setting up a plugin for the IDE of their choice.
We could potentially also implement Vale in our CI pipeline. However, that may require careful implementation. For example, while Vale can encourage people to write in the "active voice," that's not appropriate for all writing situations.
What does success look like, and how can we measure that?
Documentation that conforms to GitLab style guidelines, with reduced effort. Specifically, once Vale is implemented, I'd expect fewer and/or smaller MRs to harmonize our documentation with GitLab standards.
Links / references
- https://github.com/errata-ai/vale
- https://errata-ai.github.io/vale/
- https://github.com/testthedocs/vale-styles
Related issue(s):
I believe this proposal should supersede this proposal to use Proselint: #23480 (closed). At least per https://errata.ai/vale/, it already includes "pre-made" styles for Proselint.
Best guess: Vale should work "hand-in-hand" with this issue that implemented the markdownlint
tool: gitlab-foss#47704 (closed). There is some overlap; example, our implementation of markdownlint
includes functionality to capitalize proper names, per !20764 (diffs) (which is also doable in Vale).