How to introduce prose linters at your workplace

Prose linters are great at checking documentation against style guides, either in code editors or when running a CI/CD pipeline. They can capture issues in your docs that might have been overlooked by reviewers, thus avoiding costly mistakes. The bigger problem is how to bring the value of linters to our day-to-day jobs. How do you persuade colleagues to use them when drafting docs? It takes a little patience and ingenuity.

The following advice comes from my experience with implementing the Vale prose linter at work, and from conversations with fellow technical writers who had to go through similar ordeals. With some modifications, you can use this guide for any new tool or technology you seek to introduce at your workplace.

Identify the pain points

New technology, such as prose linters, should solve existing issues and improve current processes while adding minimal overhead. Existing linters are quite easy to setup, although they’re still far from perfect when it comes to user experience. If you end up adding extra work, you’d negate the benefits of the tech you want to implement.

Before introducing a prose linter such as Vale, ask yourself the following questions:

• What processes do you need to improve? Perhaps you want to shorten editing time, or maybe the peer-review process. Are there consistency issues in your docs? Do you need to lower bug metrics? On-boarding can also benefit from prose linters, as they teach new writers about the writing rules in your team. Based on your experience, think on how a prose linter can help the team.
• What existing technology do you use to author documentation at work? If you’re doing docs-as-code, most prose linters will likely work with your setup, though be mindful of compatibility: The less additional pieces are required to get started, the better.
• Do you have an existing style guide? Some companies already have style guides for documentation, or follow existing style guides, such as Google’s. If you don’t have a style guide yet, you’ll be not only introducing a prose linter, but also style guides, whose raison d’être is consistency and quality in documentation. The introduction of a prose linter can be a wonderful trojan horse for style guides.

Showcase the value

Few people might know already about the technology you’d like to bring at work, and while mentioning it in passing in a team meeting or channel might gauge interest, it won’t move the needle towards adoption. To increase engagement, you must showcase the value of prose linters by creating a meaningful demo or prototype.

• Take advantage of in-house hackatons or personal projects to create a small demo of the prose linter. I once used a two-day hackaton to port most of an existing style guide to Vale rules, setting up an internal repo with demo content and a demo CI/CD pipeline. Then, I recorded a brief video demo.
• Rules coverage doesn’t matter as long as you can show how a prose linter works in your setup without requiring excessive overhead. You can take an existing document, some rules, and record the linter in the terminal. That already shows how fast a linter can be at catching the most outrageous blunders.
• Use the demo sessions at your disposal to demo the linter. Start with your team, then look for demo opportunities in your engineering or product department, or during a company meeting. If no such occasions exist, create one by inviting people to a demo (with free pizza, of course). A prose linter can be used by everyone, and engineers can be quite enthusiastic about them, as they’re already familiar with code linters.

Reduce the friction

Depending on how work is done at your organization, you might not need any kind of permission to go ahead and continue working on the prose linter. On one hand, you want to reduce onboarding friction, so that the prose linter is easy to install and use; on the other, you want colleagues to use your shiny linter and send you feedback.

• Eat your own dog food. This is a technical mantra that I follow in almost everything I do at work: if you’re not the first adopter, there is no point in promoting a technology.
• Write an internal guide on how to use the linter (in Notion, Confluence, Slab, Drive). Test drive the guide with some volunteers to identify flaws or compatibility issues.
• Communicate new releases of the linter in a team channel or blog. Regular updates help people become aware of the prose linter.
• If management agrees, make the usage of the linter part of the team onboarding. For example, it can be part of the same training session focused on tools.
• Set up a Vale package in an accessible repository so that anyone can clone the style in their local machine. Alternatively, add the style as a git submodule to the main repo, though be aware that submodules can be quite problematic for most users.
• Be available to help. Be the ambassador of the tool you’re bringing. Set up office hours, a dedicated Slack channel, a mailing list, or whatever suits your needs.

CI/CD, with caution

The temptation of rolling out a prose linter in your docs release pipeline can be great. What’s not to like about automated style checks before rolling out docs? When I discussed this with Marcel Amirault from GitLab, he gave me a great piece of advice: roll out the linter rules progressively. For example, if your Vale style is made of 50 rules, start with 5 and see how that goes: you might have to alter the error level for each rule, or tweak them so as not to choke the pipeline. Rinse and repeat until all are in production.