Vale
Lint your docs, stay current with upstream style guide changes, and customize your own rules and vocabulary to reflect your style preferences with Vale.
There’s a difference between claiming to follow a style guide and actually testing against it. Vale is a tool that can bridge that gap and keep your writing honest. Nobody can keep all those style guide rules in their head, and with Vale, you won’t have to! Vale is a command line tool at its core, but there’s good plugin support in popular text editors like VS Code and Vim.
Here’s how I’ve configured Vale for this project. See my customizations below.
styles/
├── config/
│ └── vocabularies/
│ └── portfolio/
│ └── accept.txt
├── Google/
│ └── rules.yml
├── portfolio/
│ └── FleschKincaid.yml
├── Readability/
│ └── rules.yml
└── write-good/
└── rules.yml
.vale.iniCustomizations
One of Vale’s greatest strength is the ability to customize it. If your organization’s style rules differ slightly from Google’s, for example, Vale makes it possible to adjust rules to your liking. You can even update the rule’s description text, severity, and style guide hyperlink. In the past, I’ve linked custom rules to the doc team’s Confluence which provided a detailed rationale for certain style decisions.
There’s a proper way to ensure your customizations aren’t overwritten, though. It’s not enough to remove rules you don’t want to apply from a chosen style guide. Once you run vale sync or reinstall the app, those local changes are overwritten by the upstream source. To preserve customization, it’s better to turn off specific rules in your .vale.ini configuration file. For rules you want to keep but modify, extend them in your own custom style. You can then store this configuration in version control where they’ll persist across syncs and installs.
|
Update your .gitignore for Vale
|
Vale configuration file
Here’s my vale configuration for this project. In general, I prefer Google’s style guide to Microsoft or RedHat since I find it a bit less rigid and more conversational. This helps me fight jargon and keep docs simple.
I’ve turned off several rules at the bottom of this file that I’d normally leave enabled. But, because this is a portfolio, I’ve allowed myself a few cliches, weasel words, and exclamation points as an indulgence!
Vale includes several readability metrics by default. I’ve turned all off except the FleschKincaid grade level rule. I prefer this metric since it focuses on syllable count rather than word count. Cadence is more important than word count, in my opinion. In addition to keeping this readability metric, I’ve extended it into my own portfolio style and increased the grade level from 8 to 9.
StylesPath = .github/styles
MinAlertLevel = warning
Vocab = portfolio
Packages = Google, write-good, Readability
[*{.md,.adoc}]
BasedOnStyles = Vale, Google, write-good, Readability, portfolio
## LOCAL RULES CONFIG
Google.FirstPerson = NO
Google.Exclamation = NO
write-good.TooWordy = NO
write-good.Weasel = NO
Readability.GunningFog = NO
Readability.ColemanLiau = NO
Readability.LIX = NO
Readability.SMOG = NO
# extended in porfolio.FleschKincaid
Readability.FleschKincaid = NO
Readability.FleschReadingEase = NO
Readability.AutomatedReadability = NOVocabulary
I’ve maintained a custom vocab list for Vale at styles/config/vocabularies/portfolio. All terms in this list get added as an "exception" to each style rule. This centralized list separates it from the synced packages, so it won’t be overwritten by upstream changes over time.
Antora
(?i)shortcodes?
Jira
Confluence
GitHub
Neovim
Atlassian's
hotfix
hotfixes
xyz
SME
Kanban
dev
methodology
check-in
touch-point
RTFM
MadCap Flare
AsciiDoc
xkcd
XHTML
VS Code
PDF
Markdown
N. Parker Jones
Git's
repo
TOCs
Microsoft Word
Pandoc
Global Project Linking
hoc
overcommitted
unassigning
roadmaps
siloed
Includes Page
GetPage
Infrastructure as Code
ifdef
ifndef
reinvent the wheel