Update spelling and capitalization linting in the docs

Problem to solve

With continued updates to the Vale linter, we can move capitalization checking out of markdownlint and into Vale. As part of this, we can now make use of Vale vocabularies: https://vale.sh/docs/topics/vocab/

  • Before: 0 errors, 7033 warnings and 9332 suggestions in 2315 files.
  • After moving to Vale.Terms: 0 errors, 6608 warnings and 8977 suggestions in 2315 files.

Proposal

  • Clean up the split between Terms and Spelling before disseminating these rule changes out to other repos.
  • Do a review of the spelling words and move the appropriate ones to Terms
  • Review and update https://docs.gitlab.com/ee/development/documentation/testing/vale.html. Our instructions all assume rules are named gitlab.* and this new rule would be Vale.Terms, Vale.Spelling and Vale.Repetition.
  • Consider code comments in these files, explaining what words should go in each place:
    • doc/.vale/config/vocabularies/gitlab_vocab/accept.txt
    • doc/.vale/gitlab/spelling-exceptions.txt
  • Consider a code comment in .markdownlint-cli2.yaml explaining where those terms went
  • Redraft the user-facing messages for the spelling and terms rules to reflect current state
  • Update https://docs.gitlab.com/ee/development/documentation/styleguide/ or one of the child pages to explain the differences between the spelling rule and the terms rule - and why spelling is warning level while terms is error level.

Other links/references

Edited by Marcel Amirault