Earlier this week, Alan Pringle posted Adapt or die: style guide edition. Like a lot of good advice, it will leave sensible readers (such as yourself) thinking that it’s an unremarkable advisory that goes without saying. But it may also leave you uneasy that there may be writers who haven’t already learned that fussing over style guides is a bit self-indulgent. It’s quite good, though I got tripped up over what’s practically a throwaway line:

If you start a new job and don’t like a decision in a style guide, join the club and suck it up (unless you have a truly compelling argument).

I stopped on that line because knowing whether you’ve got a good argument to do something is the only genuinely hard problem in developing content, style guides included. What constitutes a “truly compelling argument” isn’t necessarily obvious. Nearly every style guide fight I’ve witnessed had at least one person who believed their quibble represented a “truly compelling argument.”

I suspect many trivial arguments can be short-circuited by having, along with the style guide, expectations about what the style guide is meant to achieve. In the absence of clear expectations, “truly compelling” is whatever proponents and opponents of a change think is important. So, I offer to you the following template for a style guide hierarchy of importance, with sample rules and sample compelling arguments:

Writability

If a rule is a huge pain to implement, it’s out. If it’s easy to do, it’s in.

Example rule: The company name is always followed by the trademark symbol.

Example argument: Seriously, you’re going to Make™ Me™ Do™ This™ All™ Day™?

Readability

Clarity is important. The style guide should favor understanding over confusion. If a rule makes it harder to understand something, it’s out. If it’s easier to understand something, it’s in.

Example rule: Never use the serial comma.

Example argument: The serial comma is sometimes needed to resolve ambiguity that cannot be resolved by reordering words.

Maintainability

Documentation should be made to last, and it can’t last without reliable upkeep. If a rule is hard to maintain, it’s out. If the rule is easy to maintain, it’s in. Special cases are special cases of pain.

Example rule: The software package’s name should be all lowercase, unless it appears at the beginning of a sentence or headings greater than level three.

Example argument: Too many special cases. The package name should always be lowercase or always uppercase because it’s way easier to verify correct usage if it’s the same usage everywhere.

Unity

There is one and only one style guide. One and only one person is the author of the style guide. That one and only one person is the final arbiter of what goes in, of what comes out, and of what adheres to the style guide.

Example rule: You’re free to end a sentence with a preposition, if you want to¹. Go nuts.

Example argument: Trick example. There is no compelling argument against the rule. Daniel’s style guide, Daniel’s rules.

Note that these criteria are not coequal, as each criterion trumps the preceding criteria:

Writability < Readability < Maintainability < Unity

Your approach might not be the same as mine (maybe you favor readability over maintainability, or the addition of some other criteria), but there needs to be a clear hierarchy of importance.

I acknowledge that this approach may lead to bad outcomes (for instance, log in and login might be argued into one strict usage under the principle of maintainability even though it hurts my English-major heart). But it’s my intention that by putting Unity above all else, one sensible person will halt any egregious style guide errors. Or to put it another way, there’s no rule that supersedes a good editor.

With clear expectations in place, style guide disputes will tend toward resolution in favor of the principle behind an argument, rather than the quality of the argument. “But Daniel,” you say, “shouldn’t good arguments win and bad arguments lose?” To which I say, emphatically, “No.” That leads to wasting time coming up with highly refined arguments for trivial style guide disputes, when you could spend that time writing the docs.