How do you write good?

For some, the answer is Grammarly. This, however, falls short to me for the following reasons:

• Needing to rely on some third party service. Seriously, what if I want to draft my blog posts without Internet?
• Not configurable. Leave me alone, sometimes I like writing my way.
• Where’s my beautiful terminal application?

I use Vale (GitHub) a linter for human prose. It runs locally on my computer ✔, is configurable by defining a rule set ✔, and offers not only a beautiful CLI application ✔, but even offers integrations to editors like VSCode.

To provide useful feedback, we’ll need a strong collection of rules. Like a crazy person, I went onto the Vale package hub and looked at the rules of many different packages and compiled the ones I liked into my own package for us to use.

All we need to do is specify the package in our Vale config. To see where this lives, you can run vale ls-dirs. For example, on my computer it is at ~/.config/vale/.vale.ini

StylesPath = /home/rozek/.local/share/vale/styles

Vocab = brozek

MinAlertLevel = suggestion

Packages = https://github.com/Brandon-Rozek/vale/releases/download/0.1.0/brozek.zip

[*]
BasedOnStyles = Vale, brozek

By default, Vale includes a spell-checker. As a technical writer, I often talk about products which Vale claims are typos. We can force Vale to not complain by creating a Vocabulary (fancy word for dictionary).

<StylesPath>/config/vocabularies/brozek/accept.txt

BTRFS
[Bb]oolean
systemd
Zulip

These vocabularies are case-sensitive, which while may seen like a weird choice, I find useful in keeping capitalization consistent. To specify that something is not case sensitive you’ll need to put square brackets around the upper and lower-case letter. For example, case-insensitive b is [Bb].

With all this configured, we can then sync the configuration rules to our machine.

vale sync

Then, lint a blog post!

vale vale-linter-human-prose.md

 vale-linter-human-prose.md
 14:48  warning     Remove 'Seriously' if it's not  brozek.Adverbs
                    important to the meaning of
                    the statement.
 20:70  suggestion  Try to keep sentences short (<  brozek.SentenceLength
                    30 words).
 48:91  warning     Remove 'really' if it's not     brozek.Adverbs
                    important to the meaning of
                    the statement.

From there you can choose which suggestions to keep and which to ignore ;)