My team has been working closely with the technical writing community this quarter. Vale is a highly-extensible linter that I learned about from one of the technical writers embedded in our team.
I’m always interested in improving my writing so a piece of tooling that can point out inconsistencies in tone rather than just spelling sounded intriguing!
This post forms half “how to get started with Vale” and half “building my own style”
Installing Vale
At time of writing, Vale is not installable through Homebrew. I downloaded a release from their page, installed it to /usr/local/bin, ran it and …
$ vale
WARNING: Missing or invalid config file.
See https://github.com/errata-ai/vale#usage for information about creating a config file.
Oh, I guess I need a configuration file first.
I made a very minimal configuration by munging the example from the Vale wiki - it belongs in a file called .vale.ini in the root of my blog project.
StylesPath = vale-styles/
MinAlertLevel = error
[*]
BasedOnStyles = write-good
vale.Editorializing = YES
vale.Hedging = error
This will work, right?
$ vale _posts/* --debug
✔ 0 errors, 0 warnings and 0 suggestions in 86 files.
I guess I need to load some styles!
Configuring styles
Vale is very extensible - I decided to start off with something simple. A lot of content guides warn about the horrors of Passive Voice so I “borrowed” some publicly available configuration from the govuk-developer-docs
I copied this to vale-styles/Tone/PassiveVoice.yml and added Tone to the configuration under BasedOnStyles.
$ vale _posts/*
✖ 0 errors, 270 warnings and 0 suggestions in 86 files.
Wow, that’s a lot of passive voice. I have a bit of editing to do in the near future. I’m going to pretend I haven’t loaded this style, and create one of my own instead.
Creating custom styles
I find myself wanting to be consistent in my technical vocabulary. Should kubernetes always be capitalised? Have I defined any acronyms I use heavily, like Test-Driven Development being shortened to TDD?
Vale has a variety of ways to configure a custom style - an existence style checks whether specific words or phrases have been used, and a substitution style suggests replacements.
extends: substitution
message: Consider using '%s' instead of '%s'
code: false
ignorecase: true
level: warning
swap:
k8s: Kubernetes
terraform: Terraform
a11y: accessibility
i18n: internationalisation
Saving this as value-styles/TechTerms/TechTerms.yml and adding TechTerms to the configuration under BasedOnStyles will wire this custom style into the linter. Testing it on my blog gives
$ vale _posts/*
_posts/2019-02-03-notes-from-the-week-17.markdown
56:170 warning Consider using 'Terraform' TechTerms.TechTerms
instead of 'terraform'
_posts/2019-02-09-notes-from-the-week-18.markdown
27:99 warning Consider using 'Terraform' TechTerms.TechTerms
instead of 'terraform'
27:197 warning Consider using 'Terraform' TechTerms.TechTerms
instead of 'terraform'
These are both legit changes that I could make!
Conclusion
I’m enjoying the experimentation with different styles and examining my own prose for patterns. And I’m apparently really bad at passive voice!
Next, I think I’ll try and codify an existing style guide and release it as a project. Both the Guardian and Telegraph publish their newspaper style guides which might be fun to codify!
November is National Blog Posting Month, or NaBloPoMo. I’ll be endeavouring to write one blog post per day in the month of November 2019 - some short and sweet, others long and boring.