How to introduce prose linters at your workplace

Jul. 3, 2022

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:

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.

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.

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.