I’m currently doing a technical writing project, and the “B-story” I’m working on while I think through “user journey” is going through all the user interface strings and cleaning them up. This is both soothingly dull, because it doesn’t require creativity, and quite useful, because any codebase has a lot of drift if it’s not checked. It was also kind of stressful, at first, because I’ve got my sticky non-coder fingers DEEP in the codebase. What if I screw up?
Then I did screw up. In the course of making an error message more human-readable, I accidentally deleted a quotation mark at the end of the string, which then screwed up the code on the next line. Of course, I didn’t notice – I wasn’t looking at the code. But when I checked in my changes, I got a merge warning back, saying something was broken, exactly here. Of course, I opened up the file to try to see what I’d done, and it was the line above here that was wrong, but it got me to within a couple characters. At no point did I have to worry that I’d introduced a product-breaking problem. Tests worked as designed!
Linters and style guides
I want to add a linter to the code tests, one for the specific problem of capitalization. A linter is a specific kind of code tests that checks your source code for syntax problems (and other kinds of problems). The one I want to add checks that the name of the product is always capitalized correctly. It’s tricky, though — you can’t just replace it everywhere, because sometimes it’s a variable name and needs to be all-lowercase. There are all sorts of text linters – spellcheck is a linter, and there are linters for grammar and inclusive language and a bunch of other things. Super-handy.
A linter is not an editor. It’s a tool that automates a style guide.
A style guide is the general and specific rules of how we’re using a language. Many tech organizations have a code style guide, but almost every organization has a few style guides for communicating with humans. There’s a brand guide, which has ferocious rules about not messing with the aspect ratio of the logo, and what exact CMYK color it’s displayed in, and maybe even something about the brand voice. There’s a style guide around the user interface and documentation that specifies what interface elements are named and how you refer to them. This would be extraordinarily tedious to write from scratch every time, so most places start with a known standard like The Microsoft Style Guide, and then you only have to write a few pages specific to your company.
It matters
Consistency matters.
Consistency matters for branding, because of copyright and recognition reasons, because you’re investing lots of money into that exact arrangement of letters.
Consistency matters for code, because computers are terrible at approximation and “close enough”.
Consistency matters for documentation, because human language is really hard and weird.
Consistency matters, but it’s wicked hard to do, because humans get bored, or their typing nerves misfire, or they are not alone on a project, or they forget from day to day what capitalization they’re supposed to be using.
So if it matters, and it’s hard to do reliably, and it involves parsing exact strings and not nuanced meaning? That’s a great place for automation.