As a technical content strategist I straddle the line between being a technical writer and a marketing writer. I’m neither, but I have similar skills. And I like to use tools from both professions. One of my favorites is Vale, which I use in VS Code Markdown files. Vale is a “prose linter” created by and for technical writers. In coding, linting refers to a process of checking code against standards. But as Vale shows, you can also use linting for prose.
Prose standards might include correct spelling and house style guidelines. For example, the GitLab docs team has a Vale rule to catch any usage of first-person pronouns (which is discouraged in docs).
Why would a content strategist like me need prose linting? Other types of content strategists typically use tools like Grammarly or just regular Google Docs grammar/spell checking. The main disadvantage of these tools for me is lack of customization. I often deal with specific rules and terminology. With Vale I can build a custom set of rules and even write my own rules. I recommend Vale for anyone who writes about tech and include it in my recommended 5 Content Marketing Resources for Technical Solo-Founders.
For example, I often write SEO Briefs, which are instructions for technical content writers. Google cuts off titles beyond 60 characters in search results and short titles often aren’t informative enough, so I want titles between 20-60 characters. I wrote a Vale rule to warn me when a title is too long or short:
# titleLength.yml
# For titles written in Markdown files as headers
extends: occurrence
message: 'Titles should be between 20 and 60 characters'
scope: heading
level: warning
max: 60
min: 20
token: .
Another one is my clients have different standards for title capitalization. My main client uses the Chicago Manual of Style convention, so I have this rule enabled:
# titleCapitalization.yml
# Extended from the Vultr Markdown Toolkit, released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.
# https://creativecommons.org/licenses/by/4.0/
#
extends: capitalization
message: "Headings should use title case. Client follows the Chicago Manual of Style."
# link: https://capitalizemytitle.com/style/chicago
level: error
scope: heading
match: $title
style: AP
exceptions:
- macOS
- iOS
- fs
- react-native-fs
Vultr, a hosting company, developed the original rule using Vale and shared it through open source. I then customized for personal usage, including client-specific words that I do not want capitalized like iOS. Many open source Vale rules are available to use or build upon. Vale has a nice list of their own, I also like Vultr’s and GitLab’s. The Write The Docs Slack has an active Vale community for discussion and questions.
I use Vale rules to catch passive voice and cliches, among other common writing annoyances. If you’d like to see (or copy) my Vale rules and configuration, I’ve put the files up on GitHub.
What’s the catch? Setting up Vale has a learning curve and writing your own rules is even harder. If you use the free version of Vale, you need to know how to install Vale on the command line and learn how to format the Vale configuration files. For writing rules, you often need to use regular expressions, which are infamously tricky.
Of course, not everyone wants to or needs to write in VS Code. I learned VS Code as a developer and in my current career I still do some technical content that involves writing within code files or using code embedded in text files. Before I started using Vale, I often ended up with spelling or grammar mistakes in my code comments or documentation files. If I wanted these files checked I’d have to paste them into Google Docs (to use Grammarly) or send them to an editor, which was laborious. For client-specific standards I had to check for them manually. Vale solved all these issues.
For this very post I added custom Vale vocabulary to reject misspelling and misformattings of “VS Code” like “VSCode” or “VScode”. It’s also nice to have all your custom spelling and grammar rules in files that you can share with others and backup on GitHub.
For non VS Code fans, Vale has an easy-to-install paid desktop application called Vale Server, which works in Google Docs and in text fields on the Chrome browser. Personally, I still use Google Docs sometimes because it does catch more complicated grammar errors that Vale misses. It caught two errors in this post, both related to inconsistent pluralization within a sentence. So I’m considering getting the desktop version of Vale.
Vale is also not the only reason I use VS Code for writing. In a future post, I’ll discuss a bunch of other VS Code extensions I use for fixing bad Markdown and automating repetitive tasks. Sign up for my newsletter to get this and other posts delivered to your inbox.