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”
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!
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
$ 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!
I’m enjoying the experimentation with different styles and examining my own prose for patterns. And I’m apparently really bad at passive voice!
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.