Rorybot: Automated content style checking
The Docs team at Shopify has an editor named Rory. He’s brilliant. He’s got a PhD in English. And one of his duties is to review changes to the pages that make up the Shopify Help Center before they go live and ensure they meet Shopify’s documentation style guide standards.
Much of the style guide is comprised of substitutions (for example, “Use ‘log in to’. Don’t use ‘log into’.”). So up until recently, Rory spent a lot of time correcting hyphen usage and flagging unwanted vocabulary. Rory is good at this task, just like he’s good at most things involving words. But my colleague Adam and I realized that a computer program could also do this task, which would let Rory use his time for higher-level tasks that only he can do.
During Hack Days—a quarterly event during which Shopify employees are encouraged to conceptualize and ship projects within 48 hours—Adam and I adapted an open-source Node.js program called Alex into a tool we called Rorybot.
Rorybot finds style errors in text files (formats such as HTML or Markdown, as opposed to binary formats like Microsoft Word) by comparing the input text against a Shopify-specific library of incorrect terms and raising errors when it finds a match. The error message explains why certain word choices are incorrect according to the Shopify documentation style guide and suggests alternatives.
You can run Rorybot from the command line, which lets you check a bunch of files at once, or install plugins for the text editors Atom and Sublime Text that check your text as you type.
Since we put Rorybot together with limited knowledge and great scrappiness for a specific internal purpose, it’s far from a turnkey solution for other organizations. You are more than welcome to fork Rorybot and retext-shopify (our library) and use it to build your own solution, however, and I’m happy to answer any questions.
Rorybot is also written in Node.js, whereas Shopify primarily uses Ruby on Rails. As a result, I’m not going to do any further work on this incarnation of Rorybot and instead am focusing my effort on producing similar functionality using Ruby.
Right now, I am working on integrating Rorybot’s pattern-matching into my colleague Justin’s erb-lint Ruby gem. When development is complete, erb-lint will allow checks on application text content to run alongside checks on application code whenever developers push changes to the central repository.
The second phase will be adapting my work on erb-lint into an exact replacement for Rorybot (but written in Ruby and with the aim of making changing rules according to your organization’s needs as easy as possible).
So, watch this space. I’ll post about it again as soon as I’ve got something to share, and next time hopefully it’ll be something you can implement right away for your organization.
