Most technical standards I have encountered were written once, read twice, and ignored. Not out of rebellion. 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 did follow, and failed with more than a few that they did not. Here is what I think separates them.
Brief enough to hold in your head
A standard is only useful if an engineer can remember it while working. That puts a hard limit on length. A page or two of rules will be followed. Forty pages will be searched when someone is in trouble and otherwise forgotten.
So I think the discipline of writing a standard is mostly the discipline of leaving things out. If a rule does not prevent a real problem the team has actually had, it does not belong. If two rules can be one, they should be. The question for every line is whether the team would be measurably worse off without it.
Every rule says why
A rule without a reason is an order, and engineers are bad at following orders they do not understand, which I think is a feature of engineers rather than a flaw. A rule with a reason is a tool. The engineer can tell when it applies, when it does not, and when the situation in front of them is one the author did not anticipate.
The reason also keeps the rule honest. When the reason stops being true, because the platform changed or the problem went away, 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. The parts that can be checked by a linter, a type, a template, or a pipeline step should be checked there, automatically, on every change. Those parts stop being rules people follow and become properties the codebase has.
What is left in the document is the part that genuinely needs judgment: the architectural decisions, the trade-offs, the things a machine cannot check. That part is short, which is what the first point asked for, and it is the part worth reading.
Someone owns it
A standard without an owner decays. The platform moves, the team learns something, a rule turns out to be wrong, and nobody has the standing to change the document, so it drifts from the truth until it is ignored. I think every standard needs a named owner, with the authority to change it and the expectation that they will, and a date on it so readers know how stale it might be.
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, and the standard loses its credibility one exception at a time.
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. It is how the owner finds out that the standard has a gap, and every few exceptions of the same kind are a signal that 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 (0)