When I joined the Stoplight team as a technical writer in March, 2022, I was really excited to learn more about the product, and also to explore ways to improve documentation with code. I had already learned during the interview process that Stoplight was following a “Docs as Code” philosophy, by using Stoplight itself to write documentation for the product and using GitHub for hosting and version control. So I was curious to learn what other tools and processes we could use and/or automate to improve the quality of our documentation and the release process, which some people refer to as “DocOps.”
One of the many ways to write better documentation is to adopt a writing style guide. A writing style guide can be as simple as certain word conventions, for example how to capitalize a company’s name (GitHub, not Github), to full-fledged tomes of rules that cover how the style and voice of your writing should come across. The Microsoft Writing Style Guide, for example, has been around since 1995, but is still constantly updated and is very popular among technical writers.
There are a lot of benefits to following a writing style guide:
- It helps teams maintain a consistent style, and voice, across their documentation
- Improve collaboration by having clear rules to follow. It can help avoid common discussions and arguments on certain topics (you don’t want to have writers arguing about using contractions or not for hours)
- Having a consistent style can help reduce users’ cognitive load
- It can have a measurable impact in improving docs accessibility and reducing bias
Just like text editors have features that help users see when they misspelled words, there are tools out there that allow you to create and enforce a writing style guide. For example, Grammarly Business has a specific feature focused on style guides. But there’s also an open-source tool called Vale that we have started using at Stoplight to make sure our documentation is following the Microsoft Writing Style Guide as closely as possible.
What is Vale
Vale is a free, open-source, command-line tool that teams can use to enforce a style guide and any custom sets of rules on text files. All you have to do is create a configuration file and create or import a set of rules, and you can start linting your documentation.
There are a lot of cool things about Vale that make it especially useful for tech writers:
- It understands markup well, so you can use it on Markdown, AsciiDoc, reStructuredText, and other files, without having a bunch of issues or false positives because of markup formatting
- It’s extensible, so you can use one or more style guides that people have already created, or write your own set of rules
- It works offline
- It can be used in your terminal, code editor, or even as part of your CI/CD pipeline
- It’s free and open-source!
This is what errors look like when you have a project configured with Vale and with the Vale Visual Studio Code extension installed:
How We Added Vale to Our Writing Process
Just like taking a design-first approach with APIs can save a lot of headaches and time, following a writing style guide from the start can be much easier than adopting one when you already have existing docs. But it’s not impossible!
We have been putting a lot of work into improving the Stoplight documentation, and adopting a style guide was an obvious next step for us. But we knew that it was going to be a lot of work to review all of our product documentation and that it was probably not a good idea to try to add Vale to our CI/CD pipeline right out of the gate. So we broke down our plan into a few steps:
1. Pick one style guide
We decided to start by following the Microsoft Writing Style Guide. Pam Goodrich, our Tech Writer Manager, was already familiar with the style guide, and it’s also a great and popular style guide that a lot of tech writers use, so we thought it would be a good starting point as the team grows.
2. Split up the work
We are currently a team of two writers, so we split up the work based on how our product documentation was organized into different sections. This was also a great opportunity to revisit some of the older topics in our documentation to update them or even delete some of them.
3. Customize Vale for our own use case
Every company is going to have specific use cases, language, or acronyms that are relevant to them. One great thing about Vale is that it’s really customizable! So as we reviewed each section of our product documentation, we learned which rules of the Microsoft Writing Style Guide we thought did not apply to our use case and for our readers, and so we turned certain rules off or changed the alert level for them. Vale also has a “Vocabulary” feature, where you can have a list of specific words that Vale can accept or reject. It’s a great way to add names of companies with specific spellings, or acronyms that are acceptable for your audience that you don’t want Vale to think are errors. We made sure to add “Spotlight” to our list of words to reject since that’s a common mistake we find even internally and since it’s a known word, most spellcheck tools won’t flag it.
4. Add Vale to CI/CD pipeline
Once we reviewed our product docs and customized our Vale configuration, we felt confident that we could add Vale to our CI/CD pipeline. That way, anyone in the team who contributes to the docs can pick up and review any errors that Vale throws, without having to manually install the Vale command-line tool or code editor extensions. Since we use GitHub to host our documentation, all we had to do was add the Vale GitHub action to our project, and we were good to go!
Tips and Tricks
After going through this process, here are a few things we have learned that might be helpful if you’re thinking about using Vale in your projects:
Don’t edit other style guides files
if you’re using the Microsoft Writing Style Guide, Google’s, or any other set of files, we think it’s a good idea to not edit those files directly. That is for two reasons:
- If there are updates to an external style guide and you have to download those files and update them in your project, it would be very easy for the changes you made to be lost.
- When new people are onboarded, having modified style guide rules under the original package name (for example, Microsoft or Google) can cause confusion over time.
If you want to make modifications to a style guide, a good approach is to create your own style guide folder, customize your rules as you see fit there, and then turn off the rules you want to ignore in the original style guide.
Vale is not a replacement for other tools
You can find this sentence in the Vale docs: “Vale doesn’t teach you how to write; it’s a tool for writers.” So if you’re looking for a tool that will give you feedback on how to improve your writing skills (such as telling when you can be more concise, or that a phrase or paragraph is too complex), you should use other tools such as Grammarly or Hemingway.
Learn from other Vale users
Vale is used by a lot of companies and teams, and they have a great list in their docs. It can be helpful to take a look at how other projects use Vale, what kind of style guides they follow, the rules they turn on or off, and the words they add to their Vocabulary folder as you start working on your own Vale configuration settings.
Next Steps
Since Vale is so customizable, we would still like to do more with it! As we mentioned, we thought it was a good idea to start small and only add the Microsoft Writing Style Guide to our Vale configuration at first. But there are several other sets of rules that we would like to investigate and see how we could use them to improve our documentation. We also have plans to add Vale to some of Stoplight’s open-source projects, as well as to our internal projects. We believe that just as important as improving our public documentation is to help our readers use our product, having better internal documentation can help all the teams at Stoplight to do better work.
We have also played around with the idea of adding Vale support to the Stoplight product, so as you’re writing articles in the Stoplight editor, you could have a Vale configuration file that would lint articles and show any errors in the problems tab. If that’s something you would like to see, take a look at our roadmap and let us know.
