Yesterday I wrote about the markdown linters we use at Mapbox. Our other test suite focuses on language and asserts the Mapbox documentation styleguide. Our copyeditor is a fork of alex, which helps you find gender favoring, polarizing, race related, religion inconsiderate, or other unequal phrasing in text.
We forked alex to add more retext plugins and introduce our own.
- retext-repeated-words - checks for repeated words.
retext-indefinite-article - checks if indefinite articles (
an) are used correctly.
- retext-simplify - checks phrases for simpler alternatives.
- retext-passive - checks for passive voice.
- retext-spell - checks spelling.
Configuration and context
With content tests, context is everything. Our copyeditor has custom configurations for any plugin that allows it. For example, for the retext-equality plugin, we allow the word
disabled. Where in some writing this word is polarizing, at Mapbox we are referring to a disabled feature or button.
alex, and by extension our copyeditor, allows the contributor to disable one or more rules in three ways:
- Inline with an HTML comment
- For an entire file
- For an entire repository
The methods above give us flexibility to adjust our tests based on the content without having to wait for a new copyeditor release.
Forever expanding dictionary
A spellchecker is incredibly useful, but you must be prepared to teach it new words. Our copyeditor comes with a dictionary of words that are common at Mapbox. And, more importantly, each repository can define its own local dictionary so that the contributor can add and commit words while writing.
The Mapbox styleguide
Our copyeditor also has a custom retext plugin to support our voice and tone and to format words and phrases consistently. Some examples:
- Avoid words like
a bit, and
justwhich minimize complexity.
- Avoid superlatives and hyperbole like
veryand instead use facts to convey meaning.
- Colloquial and idiomatic phrases rarely make sense when translated. Replace phrases like
on the flywith
keep in mindwith
- Help keep the voice of our documentation consistent, replace
Tests as a teaching tool
We want to make sure that the error messages give a clear explanation of the change so that the contributor can understand why and how the change will improve documentation. Through our copyeditor tests, we multiplied our documentation team since at any time of day a team member can get their first content review as soon as they commit their changes to GitHub.
Did you enjoy this post? Support Black Girls Code. Black Girls Code's empowers young women of color ages 7-17 to embrace the current tech marketplace as builders and creators.