Don't worry, it's ... Probably Fine

Linting my prose with Vale

16 Nov 2019

nablopomo19 blogging

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.