Writing technical standards people follow

Technical standards are often written once, read twice, and then forgotten. They can be forty pages long, unclear, and not enforced by anyone who wrote them. The truth of a standard may be fleeting, as it becomes fiction a year later. Writing a standard that teams actually follow requires brevity and relevance. A standard should be concise enough to be remembered while working, limiting its length to a page or two of rules.

Every rule must have a clear reason - a tool that engineers can understand and apply when appropriate, while also being able to identify when the situation is beyond the rule's scope. Rules without reasons quickly become obsolete as circumstances change. Automated checks through tools like linters, type-checkers, templates, or pipeline steps should handle any rules that can be enforced.

The remaining rules should focus on architectural decisions, trade-offs, and judgment calls that machines cannot verify. These are the parts that truly require human insight. An owner is essential for every standard, with the authority to modify it and the responsibility to keep it current. An exception process allows the team to break a rule when necessary, clearly stating why the deviation is required and seeking approval from at least one other person.

This process ensures the credibility of the standard, as exceptions reveal gaps that need to be addressed. Ultimately, a technical standard aims to make decisions once, sparing teams from having to make the same choices repeatedly. For this to work, standards must be few, reasoned, enforced, and regularly updated by someone who genuinely cares about their accuracy and relevance.