My journey into learning more about testing documentation began a few months ago. I joined the Write the Docs Slack group because I wanted to learn more about technical writing trends and tools. As I learned more about technical writing tools and processes, one term came up a few times: docs as code.
A quick Google search told me that docs as code essentially means:
I work on a team that uses the docs as code workflow to some extent, so I was familiar with writing documentation in Markdown and using Git for version control, and somewhat familiar with building and deploying a documentation site, but I had no experience with testing documentation. So I decided to learn more about it.
If you read my previous post, technical writers and other documentation specialists use linters to test their documentation.
Linters for code look for syntax errors, code smells, typos, and other bugs. Linters for documentation look for style errors, spelling and punctuation errors, or broken links.
Two popular linters I've learned about are write-good and Vale. Both are useful for writers looking to make sure that their documentation has a consistent style, consistent tone, and no spelling/grammar errors.
If you're interested in using Vale, you can either use the desktop application, Vale Server, or the command-line interface (CLI) for linting. I personally like Vale because you can customize it to use third-party styles or even create your own rules specific to your company's brand guidelines.
Because docs as code and testing documentation are growing in popularity, I thought it'd be useful to write a three-part series that teaches the basics of using Vale. This series will focus on the CLI, not the application.
By the end of the series, you'll know how to install, configure, and lint your own documentation files. Look out for part one soon!