field notes
Short notes from real engineering work: one decision, one incident, one reversal at a time. Each one names the shape of the problem, the tension that made it hard, the decision, and what it cost. The internals stay out — the codename is the hint.
If you have five minutes rather than an afternoon: the three case studies condense this material to one problem, one decision and what the decision cost. The notes below are the record those studies cite — and the projects the codenames belong to are on the front page.
The tree is assumed to be the truth about what is running, and occasionally it is not. Somebody changes a running system by hand, the change works, no failure forces the tree to catch up, and from that moment the source and the machine…
One repository held the record of decisions, the sequence that acts on them, the bootstrap that prepares a blank machine, and the definitions of the machines themselves. Nothing was wrong with it. It was organised by ownership, which put…
An operations document is read by an actor with no memory and full permission. That reader is not looking for orientation; it is about to change something, and the document is the only thing standing between its competence and the system.
An interrogation of a system's own documentation returned eighty-seven questions, every one answered, and that is where most exercises of the kind end: a document of findings, correct, complete, unread. Findings are not work. A list of them…
A system that helps write its own documentation produces confident prose about things it does not know. The failure is not a lie. It is a guess that is well formed and sits in a document that is otherwise correct, which is the hardest kind…
A tree that grows module by module accumulates a particular kind of artifact: the thing that is named, is plausible, and is not used. This one had a module for a shared topology layer that nothing else depended on. Nothing was deployed from…
Two registers had grown to cover the same ground. One was meant to hold only claims that cut across the whole estate; over time it had acquired role definitions and storage rules that were true of exactly one system, because that was where…
Identifiers get allocated by whoever is holding the pen, drawn from a numeric space that seemed large when it was chosen. Two registers feeding the same system had each grown entries in the same block of numbers, for unrelated subjects, so…
A record field that can hold only true or false cannot hold "nobody has decided this". Written as a yes-or-no, an open question reads as a no, and a register full of noes looks like a system that considered everything and declined, which is…
Turning a document into something a build can verify gives it a machine reader, and a machine reader is a new place to be wrong. The claims were prose — which components connect to which, what has to sit between them, the chains those…
Prose about a system has no way to notice that the system moved. The sentence written confidently one month and false the next looks identical, and the reader has no instrument except the age of the file, which measures when somebody last…
A document that lists every decision a system rests on can only be trusted if it is complete, and a complete register written by hand costs a person's attention in proportion to how much has been decided. That cost is paid exactly when…
method
Not a changelog entry and not a repository summary. One decision, one incident, one reversal, or one hard-won invariant — the thing an engineer would tell you at a whiteboard.
Prefer records with dates and root causes? Those are on incidents. Live numbers are on stats.