Introduce automated documentation linting

Goal 🏁

Improve consistency across the documentation for both readers and writers. Or at least highlight the inconsistencies.

This suggestion is prompted:

• by @lucyb's mention of the alex linter
• by my reading around "docs as code" tooling

Tooling 🔨

There are several linting tools out there. But, Vale allows you to apply different style rules or guides taken from various different linters. You can also write your own rules in YAML.

Vale aside: there are lots of other potential tools around. But Vale is mentioned a lot.

How do other people work? 👀

For example, GitLab's technical writers use:

• Text content and writing style: markdownlint, Vale
• Text formatting: Markdownlint, yamllint
• Link validity: nanoc
• File permissions and naming: lint-doc.sh

I'm more interested in the stages, than the specific tools chosen by the GitLab team. We don't have any of these right now. I also opened #642 for link checking as I believe that's a self-contained problem.

Note that tools like markdownlint are actually focused on markup consistency, not content consistency. This might be another benefit. We — understandably — have a mixture of Markdown styles across our documentation due to different author contributions.

Considerations 💭

• Is this a good idea, in principle?
• Are the checks useful or distractingly noisy?
• Would this add friction for less regular contributors?
• Should failed linting cause an outright failure of a build, or just alert "content managers" to this to later fix up? If failing, what types of lint failures should fail a build?
• What checks do we want (relates to #519)?
• Are there issues of having consistency across imported content? We include content in the documentation from the source of cohort-extractor and Data Builder. This content may not be subject to the same checks.

No repository files or tests are named. Start by reading the linked Vale, GitLab technical-writing, and related issue references (#642 and #519), then map the proposed linting stages to this documentation project. Done would require an agreed set of checks, a decision on build failures and imported content, and documented implementation scope.