Writing Articles with Vale

If you’ve ever done any sort of continuous long form writing, you’ll eventually discover that grammar and spell checking tools In Microsoft Word, LibreOffice Writer, and other WYSIWYG (What You See Is What You Get) editors. break down and become more of a distraction than a benefit. The “one size fits all” rules for grammar and spell checking cannot hope to account for the indefinite amount of writing styles and constantly evolving word constructions.

Writing is time consuming. How long does it take to write a long form document? The answer not only depends on the writer, but also on the draft and review process which often requires another pair of eyes. Many documents are checked by hired professional editors and others yet hire Don’t have that luxury. freelancers to write for them.

For the soloist, and or casual writer, building a personal editor or another set of eyes is useful, provided that you’re willing to take on that time investment. The idea is to target a specific writing style, construct the rules, and apply it consistently to your documents.

Vale is an open source program that facilitates this approach — it’s a linter for writing documents. Vale offers no opinion on how to write. You decide that for yourself by collating Writing rules in YAML (YAML Ain’t Markup Language). a set of grammatical rules and word primitives. Such flexibility allows you to emulate the behaviour of applications like the Hemingway Editor. Vale is not the only program for linting These linting tools seem to be very popular among tech companies. prose — there are a plethora of similar programs such as textlint, proselint, redpen, or just basic regular expressions.

Installation

Vale is available on most MacOS, Windows, and Linux based operating systems. major platforms. Install vale for your specific operating system by following the install documentation. Predefined style templates are available for download if you need a starting point.

In my case, a wrapper in ~/.local/bin/vale is setup around the canonical vale to allow optionally Additional argument for running vale --update at the command line level. downloading a few writing style templates and setting up my configuration directory.

#!/bin/sh -eu

directory="$XDG_CONFIG_HOME/vale"
styles="$directory/styles"
mkdir -p "$directory" "$styles";

if [ "${1:-}" = "--update" ]; then
  svn export --force https://github.com/errata-ai/Google/trunk/Google         "$styles/google";
  svn export --force https://github.com/errata-ai/joblint/trunk/Joblint       "$styles/joblint";
  svn export --force https://github.com/errata-ai/Microsoft/trunk/Microsoft   "$styles/microsoft";
  svn export --force https://github.com/errata-ai/proselint/trunk/proselint   "$styles/proselint";
  svn export --force https://github.com/errata-ai/write-good/trunk/write-good "$styles/write-good";
  exit;
fi

$(which vale --all | grep --invert-match "local/bin" | head -n 1) --config "$directory/vale.ini" "$@";

The vale.ini configuration file is simple. Set a directory containing the styles, adjust the minimum alerting level, and activate the desired writing styles. The typical usage pattern is vale document.txt at the command line.

StylesPath = /home/thedro/.config/vale/styles
MinAlertLevel = suggestion

[*.{md,txt}]
#BasedOnStyles = google
#BasedOnStyles = joblint
#BasedOnStyles = microsoft
#BasedOnStyles = proselint
#BasedOnStyles = write-good
BasedOnStyles = hemingway
BasedOnStyles = dickens
BasedOnStyles = technical
BasedOnStyles = thedro

Emulating a style requires reading deeply Many popular style guides are out there if you’d rather not. into the patterns of an author’s writing. Here is a snippet of a rule set taken from the write-good style that checks for weasel words.

extends: existence
message: "'%s' is a weasel word!"
ignorecase: true
level: warning
tokens:
  - absolutely
  - accidentally
  - additionally
  - allegedly
  - alternatively
  - angrily
  - anxiously
  - approximately

Styles are the named directories that contain a set of YAML rule sets. Construct as many rules as you want to complement the desired style.

$ tree -L 3 ~/.config/vale
___ styles
|   |__ google
|   |   |__ Contractions.yml
|   |__ joblint
|   |   |__ Acronyms.yml
|   |__ microsoft
|   |   |__ Wordiness.yml
|   |__ proselint
|   |   |__ Spelling.yml
|   |__ write-good
|       |__ Weasel.yml
|__ vale.ini

Conclusion

This approach obviously requires time as you work to build up a robust rule set for a particular style. The general idea is to correct mistakes, tokenize them as rules, and iterate constantly. You’ll have a tight feedback loop that at a minimum guards the consistency of your writing, and improves your writing speed over time. Perhaps we should take my work in progress clickbait writing style for spin Not really. sometime.

BasedOnStyles = clickbait