Most technical standards I have met were written once, read twice, and ignored. The document was forty pages, it did not say why any rule existed, nothing enforced it, and the person who wrote it had moved to another team. The standard was true the day it was published and fiction a year later.
I have written a few that teams followed and more that they did not. Here is what separates them.
Brief enough to hold in your head
A standard is only useful if an engineer can remember it while working. A page or two of rules will be followed. Forty pages will be searched when someone is in trouble and otherwise forgotten.
So the discipline of writing a standard is mostly the discipline of leaving things out. If a rule does not prevent a problem the team has actually had, it does not belong. If two rules can be one, they should be.
Every rule says why
A rule without a reason is an order, and engineers are bad at following orders they do not understand, which is a feature, not a flaw. With a reason, the engineer can tell when a rule applies and when the author did not anticipate the situation. When the reason stops being true, the rule can be retired. A rule with no stated reason lives forever, because nobody can tell whether it is still needed.
Whatever can be enforced is
People should not have to remember a standard. Whatever a linter, a type, a template, or a pipeline step can check should be checked there, on every change. What is left is the part that needs judgment, the architectural decisions and trade-offs, and that part is short and worth reading.
Someone owns it
A standard without an owner decays. The platform moves, a rule turns out to be wrong, and nobody has the standing to change the document, so it drifts until it is ignored. Every standard needs a named owner with the authority to change it, and a date so readers know how stale it is.
The exception process
The last piece is a way to break the rule. Every standard will meet a case it did not anticipate, and if the only options are to follow it blindly or ignore it silently, the team will choose silence.
A good exception process is lightweight. Say what rule you are breaking, say why, get one other person to agree, and record it. The record matters more than the approval, because it is how the owner learns the standard has a gap, and a few exceptions of one kind mean the rule should change.
What a standard is for
I think a technical standard is a way of making decisions once so that nobody has to make them again. That only works if the decisions are few, reasoned, enforced where possible, and kept current by someone who cares. Everything else is documentation, and documentation is what people stop reading.
Photo source: https://photos.robertstowe.com/victoria
Top comments (2)
Short and reasoned I get, but enforced by tooling is the part I want to push on. Who owns the rule once it sits in the linter, the person who wrote the reasoning or the person who maintains the config, and what happens when the tool moves under you and the rule stops firing. When a standard exists only as a passing check, one config change can leave it unowned. The bad code is already merged by the time it surfaces. So how do you keep the why attached to the check, in a place the next person reads.
The owner should be whoever owns the standard, not whoever maintains the config. The config maintainer owns the tooling, and the standard owner decides what the rule is for. Two things keep the why attached: put the reasoning in the rule's own error message, so it shows up the moment someone trips it, and keep a link to the standard next to the rule in the config. For a rule that silently stops firing, I'd add a test that feeds it a known violation and fails if nothing is reported. Then a tool upgrade that breaks the rule shows up as a red build instead of merged code.