Are you tired of hearing how "simple" it is to deploy apps with Docker Compose, because your experience is more one of frustration? Have you read countless blog posts and forum threads that promised to teach you how to deploy apps with Docker Compose, only for one or more essential steps to be missing, outdated, or broken?
Over the last four plus years, I’ve spent a lot of time designing, building, testing, and deploying technical documentation for a range of clients. During that time, I’ve come to be a firm believer in testing documentation, just as seriously as I test the code and services to which that documentation refers.
And like anything that we do in software, while it’s generally acceptable to do it manually at first, at some point, it has to be automatable and repeatable, otherwise the likelihood of it being consistently applied rapidly diminishes over the course of time.
So, it’s for that reason that I’ve spent quite a bit of time over the last several years researching and reviewing a number of tools, both open and closed source, for reviewing technical documentation.
Of those, a number stood out, including write-good and proselint. However, thanks to the wonderful Write the Docs community, I came to learn about Vale. To quote the package’s documentation, it’s a:
Syntax-aware linter for prose built with speed and extensibility in mind.
It took a bit to get started with, at least at first for me, but after some experimentation and numerous questions to members of the community already familiar with it, I’ve integrated it in to several projects, with some excellent results.
Why Test Your Documentation’s Prose?
Just like software — or any professional endeavour — it’s extremely important to test, test, and test again. That way, errors, omissions, bugs, mistakes — anything that detracts from the quality of the offering can be spotted before it is released, well before a paying customer or client could ever find it.
Technical documentation is no different. Actually, I’d argue that it’s even more important there, because technical documentation can often be, and often is, a user’s first contact with a library, product, or service. If that initial impression (which is often free) isn’t a good one, the likelihood of them using or paying for the service is extremely limited.
So, for all of these reasons, it’s important to test technical documentation just as much as we do the software to which it refers. That’s where we use a tool, such as vale.
What is Vale?
So, what, exactly, is Vale? Well, to draw (heavily) on the package’s documentation:
Vale is a command-line tool that brings code-like linting to prose. It's cross-platform (Windows, macOS, and Linux), written in Go, and released under the MIT license. Some of its key features are: Usability, Extensibility, and Portability.
Vale can be used to lint a number of common technical documentation formats, including HTML, Markdown, AsciiDoc, reStructuredText, XML, and DITA. It comes with an extensive set of rules which are used when linting documentation. However, these rules can be both used selectively, and added to on an as-needed basis. What’s more, the configurations can be written in both INI and Yaml formats. This makes them relatively simple to read, and editable across all major operating systems, with no special software, as a text editor will suffice.
What is a Vale Style?
Here’s an example of a recent style that I created on a client project.
extends: consistency
message: "Inconsistent spelling of '%s'"
level: error
scope: text
ignorecase: false
nonword: false
# We only want one of these to appear.
either:
API: api
CLI: cli
GitHub: github
NGINX: nginx
PHP: php
RedHat: redhat
commandline: command-line
white-listing: whitelisting
Starting at the top, is the extends option.
This must be set to one of the pre-defined styles which Vale supports.
These are:
...
Message :