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
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 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
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
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
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
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
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 Not really. sometime.
BasedOnStyles = clickbait