Engineering Field Notes: Writing Down What I'd Otherwise Just Say
TLDR: Most of what I’ve learned about building software isn’t in any codebase — it’s the judgment I bring to a design review, the reason I push back on a tempting shortcut, the pattern I reach for without thinking. For years that lived only in my head and in repeated conversations. I’ve started writing it down as Field Notes: numbered, dated, status-tracked notes that each take one practice and capture its context, the approach I’d recommend, and the trade-offs it asks you to accept. They’re observations from the field, not commandments — opinions I’ll happily be argued out of. Start with ZFN-0 for how they work.
The knowledge that never gets written down
I’ve been building systems for a long time — ISPs and datacenters, voice platforms carrying a serious fraction of the world’s calls, identity infrastructure where a mistake is measured in breaches, turnarounds of codebases that were on fire when I arrived. Across all of it, the most valuable thing I accumulated wasn’t code. It was judgment. The set of positions I arrived at the hard way: what to reach for, what to avoid, and — more than anything — why.
The problem is that this kind of knowledge almost never gets written down. It comes out in the moment: a sentence in a design review, a comment on a pull request, a quick “don’t do that, here’s what bites you” in a hallway or a Slack thread. Then the conversation ends and the reasoning evaporates. Six months later someone asks the same question, and I answer it again, slightly differently, from scratch.
That’s a genuinely bad way to keep knowledge. It doesn’t reach past the handful of people who happen to be in the room. It loses the why the moment it’s spoken. And it means the same debate gets reopened over and over, with the original reasoning never quite captured anywhere durable.
Write it once, point at it forever
The fix is almost embarrassingly simple: write the thing down once, carefully, and be able to point at it.
That’s the whole idea behind Field Notes. Each one takes a single practice I keep reaching for and writes down three things:
- The context — the forces and constraints that make the practice matter. This is most of the note, because the reasoning is the part that transfers to situations I didn’t anticipate.
- The approach — what I’d actually do, stated plainly, including what I’d avoid.
- The trade-offs — what you give up by following it. Every real practice costs something; a note that pretends otherwise isn’t worth reading.
They’re numbered (ZFN-7), dated, and carry a status, so they behave like a small, browsable, citable body of work rather than a pile of blog posts. When I want to make a point, I can link to a considered version of it instead of retyping a worse version in the moment.
Notes from the field, not commandments
I want to be clear about what these are not. They’re not standards anyone has to follow. They’re not neutral surveys that carefully weigh every option and land nowhere. And they’re deliberately not called “best practices” — that phrase pretends there’s one right answer handed down from on high, and I don’t believe that’s how good engineering works.
They’re field notes: observations from someone who’s been out there building, written with a point of view, honest about the trade-offs, and open to being wrong. I spend a lot of my life now on a boat in remote parts of British Columbia and Alaska, where the systems you depend on can’t afford to be fragile and the environment doesn’t care how clever you are. That’s the posture these notes are written in — pay attention, respect the forces at play, and be honest about what you don’t know.
Which is also why each one carries a status. A note can be current (what I’d recommend now), proposed (I’m thinking out loud and want pushback), deprecated, or superseded by something I now think is better. When I change my mind, the old note stays on the record and a new one supersedes it. The history of what I used to think is part of the value — including the times I was wrong.
Why I’m doing this, honestly
Three reasons, and I’ll be straight about all of them.
First, to pass it on. The most useful thing an experienced engineer can leave behind isn’t more code — it’s the judgment behind the choices, especially the attractive alternatives that were deliberately not taken. That’s the part code can’t tell you, and it’s the part that’s usually lost.
Second, to stay sharp and stay current. Writing a position down forces me to actually defend it. Publishing it invites people to tell me where I’m wrong, which is the fastest way I know to get better. A craft you can’t explain clearly is a craft you only half understand.
Third — and I won’t pretend otherwise — to stay relevant and useful in my field. I’d rather contribute to how people think about building software than quietly drift. If a note saves someone an outage, a bad migration, or a week of rediscovering a footgun I already paid for, then it’s earned its place.
Built to be used
Field Notes are made to be consumed, not just read. The whole set is published as a machine-readable manifest at /zfn/notes.json, and every note is available as raw markdown. So they can be imported, cross-referenced, or cited by other systems — including more formal decision-record setups — using the same ZFN-N identifier. Take what’s useful; if something’s wrong, tell me why and I’ll fix it.
The first one is ZFN-0, which explains the format itself. The rest will follow as the practices I keep explaining finally get written down properly — one note at a time.