Payton: Documentation Contribution Tooling (FY22-Q3)

Overview 💪

The technical writing team uses two lint tools to help improve the docs:

• markdownlint: To catch non-standard formatting issues. Always fails the pipeline.
• Vale: To catch a wider range of issues, but also offer non-pipeline-breaking suggestions and warnings for people using Vale locally.

You can install these two tools locally to check for issues from the command line. If you use Lefthook, it can run the linters automatically to find docs issues pre-push.

If you install the plugins into your editor, you will get the kind of feedback you might get from a technical writer, but in your editor before you actually send it for review!

Markdownlint and Vale errors already fail the pipeline, so you definitely want to catch those before you push. Additionally, when you use the Vale plugin you'll start to get non-breaking suggestions and warnings that will improve your docs and make docs reviews even faster. Suggestions and warnings might look like:

• Verify this use of the word "admin". Can it be updated to "administration", "administrator", "administer", or "Admin Area"?
• Use the US spelling "standardized" instead of the British "standardised".
• Avoid words like "currently" that promise future changes, because documentation is about the current state of the product.
• Use "default branch" or `main` instead of `master`, when possible.
• See more rules at https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab)

Instructions ✅

1. (Optional) Watch the walkthrough video from Marcel: https://youtu.be/Hgu8WsuLo7o
2. Install the two linters
3. Use them in your editor