Every few months, in a panel interview or a mentoring call or once, memorably, at the back of a wedding reception where a former colleague cornered me between the cake and the dance floor, someone asks me some version of the same question: what’s your approach to documentation?

It’s usually asked a little sheepishly, as if it’s not a “real” architecture question, the way you might ask someone what brand of notebook they use rather than how they think. But I’ve come to believe it’s one of the most revealing questions you can ask an architect, because the answer tells you almost everything else about how they work: how they think about time, how they think about other people, and honestly, how much they trust their own memory.

For a long time my answer was embarrassing. I’d say something like “oh, I try to keep the wiki updated” and then quietly know that the wiki had fourteen open tabs of half-finished pages, three of which contradicted each other about how the payments service actually authenticated its callbacks. I wasn’t lying. I was just describing an intention rather than a practice, which is a very easy thing to do when nobody is checking your homework.

What changed wasn’t a framework or a tool. It was a Tuesday morning, around 2am technically, when I was on a call with an on-call engineer who was three years into her career, staring at a service I had designed two jobs ago, trying to figure out why a queue was backing up and taking down checkout with it. She had the runbook I wrote open in one tab and the actual code in another, and neither of them agreed with what she was seeing on the dashboard. I remember the specific, quiet horror of realizing that the document I’d been proud of, the one I’d spent a whole Friday afternoon polishing, was actively making her night worse. It wasn’t neutral. It was actively lying to her, politely, in complete sentences.

Here is the metaphor I keep coming back to, even though it sounds a little precious when I say it out loud: writing documentation is closer to writing a letter than writing a specification. A specification tries to be complete. A letter tries to be understood. Those are different goals, and they pull your hand in different directions.

When you write a letter to someone you care about, you don’t just transmit facts. You anticipate them. You think about what they’ll be confused by, what they’ll skim, what they’ll need to reread twice. You choose your opening line because you know it sets the mood for everything after it. You leave out things that would only be interesting to you. That’s not a lesser form of writing than a technical spec. It’s a harder one, because it requires you to hold a whole other person in your head while you write, a person who is not you, who does not have your context, and who you will probably never actually meet.

That last part matters more than it sounds like it should. Most of the documentation I write today is for someone who doesn’t exist yet. The engineer who joins the team eighteen months from now. The future version of me who has forgotten why we chose a message queue over direct calls, because by then I will have made forty other decisions and this one will have quietly slipped out of working memory. Writing for a stranger you’ll never meet is a strange discipline, but once you take it seriously, it changes what you write and how.

It also means the tone matters. I used to write documentation the way I imagined a serious engineer should: dry, declarative, a bit cold, as if warmth would somehow undermine the technical content. I don’t think that anymore. A document that sounds like a person, that occasionally says “this part is genuinely confusing, here’s why” or “we tried the obvious approach first and it didn’t work, here’s what happened,” is a document that people trust more, not less. Warmth isn’t the opposite of rigor. Often it’s what rigor looks like when it remembers there’s a reader on the other end.

I think this is why the best documentation I’ve ever read has a faint but unmistakable personality to it, the way a good letter carries the handwriting of the person who wrote it even after it’s been typed up. You can tell when someone was tired while they wrote a section, or genuinely excited about a design, or a little embarrassed about a workaround they knew wasn’t elegant. None of that shows up as an explicit sentence. It shows up in word choice, in where the emphasis lands, in the small aside that a purely mechanical writer would have cut. I used to edit those traces out of my own writing, thinking they looked unprofessional. Now I leave more of them in, because they’re often exactly what makes a reader trust that a real person thought carefully about this, rather than assembling it from a template and moving on.

I used to write one document per topic and assume it would serve everyone who ever needed it. That’s a bit like cooking one dish and assuming it’ll satisfy a toddler, a food critic, and someone who just ran a marathon. Technically it’s food. It is not, in any meaningful sense, the right food for any of them.

Now, before I write anything, I try to name the actual person I’m picturing. Not a persona in a template. An actual, specific human, even if I have to invent them. A few show up again and again in my head:

What’s freeing about naming the reader is that it gives you permission to write four different, shorter, better documents instead of one long, apologetic one that’s trying to be all things at once. A runbook for the 3am reader should be almost rude in its brevity. An architecture overview for a new teammate can afford to be a little slower, a little more like a story, because their need is orientation, not speed. Trying to serve both audiences in a single document is usually why so much documentation feels like it’s failing everyone a little bit, rather than succeeding wildly with anyone.

One distinction took me embarrassingly long to learn, and it’s this: some documents are supposed to change, and some documents are supposed to stay exactly as they are, forever, like a fossil. Treating both kinds the same way is where a lot of documentation quietly rots.

Think of a map versus a diary. A map should always reflect the current territory. If a road closes, the map is wrong until it’s updated, and an outdated map is worse than no map at all, because it actively misleads you with confidence. Your system’s current architecture diagram, your README, your onboarding guide, your “how to deploy this service” doc: these are maps. They only have value if they’re true right now. An expired map isn’t a smaller piece of value. It’s negative value, because it costs someone time and trust to discover it’s wrong.

A diary is different. A diary is a record of a moment, and it’s supposed to stay that way. An architecture decision record, the kind that explains why we chose PostgreSQL over a document store in March of a particular year, is not supposed to be updated when circumstances change. If we later migrate away from PostgreSQL, the honest move isn’t to edit that old decision and pretend we always knew better. It’s to write a new entry that says “here’s what changed, and why the original reasoning no longer holds.” The diary entry from March stays exactly as it was. It’s a snapshot of the thinking at the time, and its value is precisely that it doesn’t get revised with hindsight.

Once I started sorting documentation into these two buckets, a lot of my anxiety about “keeping things up to date” went away, because I stopped trying to keep everything up to date. Diaries don’t need updating. They need dating, and honesty about the fact that the world has moved on since. Maps need updating constantly, almost jealously, because their entire reason for existing is to be currently true.

Most technical documentation I inherit from other teams starts in the wrong place. It opens with configuration steps, or a list of environment variables, or a diagram of boxes and arrows, before it ever says what problem this thing is solving or why it exists in this particular shape. That’s a bit like being handed the instructions for assembling a bookshelf before anyone tells you it’s a bookshelf, or that you own a wall it’s meant to lean against.

I try to open every substantial document with a paragraph that answers one question honestly: what would go wrong if this didn’t exist? Not what does it do, technically, but what human or business problem does it prevent. If I can’t answer that in a sentence or two, that’s usually a sign I don’t understand the system as well as I think I do, documentation aside.

This matters because the “why” is what survives. Implementation details change constantly: a library gets swapped, a service gets renamed, a queue gets replaced with a different queue with a similar-sounding name. But the reason the system exists in roughly this shape tends to be much more stable. If your documentation leads with why, it stays useful even as the how underneath it shifts, because the reader can re-derive a lot of the how once they understand the why. If it leads with how, it becomes stale the moment a single implementation detail changes, even if the underlying reasoning is untouched.

I resisted diagrams for longer than I’d like to admit, mostly because I was better at writing than drawing, and it’s tempting to lean on what you’re already good at. But there’s a particular kind of understanding, the shape of a system, that a paragraph simply cannot deliver as fast as a good picture, no matter how well the paragraph is written. Words are sequential. Systems are not. Forcing a reader to reconstruct a shape from a sequence of sentences is asking them to do a translation job that a diagram would have done for them instantly.

The habit that changed my documents the most was simple: before I write the explanation, I sketch the picture, even if it’s rough, even if it’s just boxes and arrows on a whiteboard I photograph and clean up later. The sketch usually reveals gaps in my own understanding before a single sentence gets written. If I can’t draw how a request flows through the system, I probably can’t explain it clearly either, and the drawing tells me that faster and more honestly than staring at a blank document ever does.

I try to hold to a few small rules about the pictures themselves. A diagram should answer one question, not five. If someone needs to understand both the request flow and the failure recovery path, that’s two diagrams, not one diagram trying to be brave about it. I label the arrows with verbs, not nouns, because “publishes an event” tells a reader what’s happening in a way that a bare line labeled “events” never will. And I try to keep the visual style consistent across a whole project so a reader’s eye learns the grammar once and can reuse it everywhere: a database always looks like a cylinder, an external system is always a dashed border, and so on. Small consistency does a lot of quiet, cumulative work.

I’ve also softened my opinions on tooling over time. I used to insist that “real” diagrams belonged in a proper design tool, carefully aligned, exported at high resolution. These days I care far more about whether a diagram gets updated than whether it’s beautiful, and text-based diagrams that live next to the code they describe get updated far more often than a polished image sitting in a separate design file nobody remembers to open. A slightly rough diagram that changes the same day the system does will always beat a gorgeous one that quietly stops being true six months later. Beauty is a nice bonus. Being current is the actual job.

Even a beautifully written document fails if it lives somewhere nobody thinks to look. I’ve watched excellent documentation die quietly in a personal notes app, in a Google Doc shared with exactly three people, in a Confluence space nobody had bookmarked. The information wasn’t wrong. It was just unreachable, which for a reader in a hurry is functionally the same thing as not existing.

Over the years I’ve settled into a rough division of labour across a handful of places, and I try to be disciplined about which kind of writing goes where, rather than letting everything blur into one enormous, searchable swamp.

None of these are novel ideas on their own. What took me a while to learn is that mixing them is worse than choosing badly among them. A runbook that suddenly turns into a design essay halfway through is a runbook that will get abandoned at 3am. An ADR that reads like a runbook, all steps and no reasoning, will be useless the day someone actually needs to understand the thinking behind it. Matching the writing to its home is half the discipline.

For years I treated documentation as a solitary act, something I did at the end of a project, alone, in the quiet after everyone else had moved on to the next thing. That habit produced documents that were fluent but strangely lonely: technically accurate, occasionally elegant, and completely uninformed by anyone else’s confusion, because nobody else had been in the room while I wrote them.

The shift that helped most wasn’t a better writing process. It was simply inviting other people into the writing itself, earlier than felt natural. Before I finalize an architecture overview, I’ll now sit down with someone who wasn’t part of the original design, sometimes someone quite junior, and ask them to read it out loud while I watch their face. You learn more from a single confused pause than from a week of proofreading your own work, because you already know what you meant, and that knowledge makes you a hopeless judge of whether a stranger would understand it too.

I’ve also started treating documentation review with something close to the seriousness of code review, which used to feel a little indulgent, like polishing a doorknob nobody touches. But a document with two reviewers catches a different kind of error than a document with none: not typos, but gaps. The reviewer who wasn’t in the design meeting will ask “wait, why not just do it the simpler way?” and force you to either write down the reasoning you’d skipped or admit, honestly, that you’d skipped the reasoning entirely because you never actually settled it. Either outcome makes the document better, and both are uncomfortable in the moment, which is usually a sign they’re worth doing.

There’s a particular kind of documentation, too, that I’ve come to believe should never be written by one person alone: the postmortem. A single author, writing about an incident they were close to, will almost always, gently and unintentionally, protect themselves. Not out of dishonesty, just ordinary human self-preservation. Writing postmortems as a small group, with someone deliberately playing the role of “why did we actually make that choice, be honest,” produces a document with sharper edges and fewer soft spots, and those sharp edges are exactly what stops the same incident from happening again in eight months under a slightly different name.

None of this means documentation has to become a committee exercise, slow and diluted by consensus. Most of what I write is still drafted alone, in one sitting, the way I’d write a first draft of anything. But I’ve learned to treat that draft as genuinely provisional, an opening offer rather than a finished thing, and to actively go looking for the person most likely to be confused by it before I let myself call it done.

I learn more from my failures here than my successes, so it feels dishonest to skip them. A few still sting a little, which is probably why they taught me something.

There was a service I designed early in my career with a genuinely clever caching layer. I was proud of it. I wrote a document explaining exactly how the cache invalidation worked, step by step, and I was quite pleased with how precise it was. What I didn’t write down was why we needed that particular invalidation strategy in the first place, what problem it was solving, what we’d tried before it that hadn’t worked. Eighteen months later, a different engineer, reasonably, looked at the complexity and thought “this seems over-engineered,” simplified it, and reintroduced the exact bug the original design had been built to prevent. The how was documented perfectly. The why was only ever in my head, and my head had moved on to a different job by then.

Another one: I once wrote a wonderfully thorough onboarding document for a new system, the kind with headings and subheadings and a table of contents, and I never once mentioned that the staging environment had a known, permanent quirk where a particular integration always failed on first deploy and needed a manual retry. It wasn’t a secret. It was just so obvious to everyone already on the team that nobody thought to write it down, including me. The new engineer lost half a day to it and, reasonably, wondered what else “everyone just knows” that nobody had bothered to tell her.

I don’t love rigid frameworks, because they tend to survive past the point where they’re useful and calcify into ritual. But I do keep a short, informal checklist I run through before I consider a piece of documentation finished, and it’s saved me more than once.

It’s not a checklist to perform. It’s closer to a set of questions I ask myself the way you’d check you have your keys and your phone before leaving the house: quickly, quietly, out of habit rather than ceremony.

Documentation doesn’t decay because people are careless. It decays because systems change constantly and words don’t change themselves. Treating that decay as a moral failing, “we should have kept the docs updated,” misses the actual, structural problem: updating documentation is invisible work with no immediate reward, competing against feature work with a very visible one. Of course it loses, most of the time, unless you change the incentives rather than the willpower.

A few small habits have done more for me than any amount of guilt ever did. I try to treat “update the map” as part of the definition of done for any change that alters how a system behaves, the same way tests are part of done, not an optional extra bolted on afterward if there’s time. I’ve started adding a single, gentle line at the bottom of the more important living documents: “last confirmed accurate on [date] by [name].” It doesn’t guarantee accuracy, but it turns silent, invisible staleness into a visible, honest signal, and an honest “this might be out of date, check with someone” is worth more than a confident, unmarked lie.

And every few months, I try to actually sit with a new teammate while they read the onboarding documentation for the first time, watching where they hesitate, where they reread a paragraph, where they quietly open a second tab to ask someone in chat instead of trusting the doc. That fifteen minutes of watching teaches me more about what’s wrong with our documentation than a year of assuming it’s fine because nobody’s complained.

I’ve also come to believe that documentation without a named owner is documentation that’s already begun to decay, even if nobody’s noticed yet. Not an owner in the sense of “the person who gets blamed,” but in the much gentler sense of “the person who would feel a small, specific discomfort if this page were wrong.” Ownerless documents drift because drift is nobody’s particular problem, which quietly means it’s everybody’s, which in practice means it’s no one’s. The teams I’ve seen keep their documentation healthiest longest are the ones that treat updating a map as ordinary, unremarkable maintenance, the same unglamorous way you’d expect someone to top up the office coffee or replace a burnt-out lightbulb: not heroic, just part of taking care of a shared place.

So, back to the question. What’s my approach to documentation as an architect? I’ve stopped answering it with a process, because I don’t think it’s really a process question underneath. It’s a question about who you’re willing to imagine while you work: a stressed engineer at 3am, a new teammate on their second week, a future version of yourself who has forgotten more than you’d like to admit. Good documentation is what happens when you take that imagining seriously enough to slow down for it.

I still don’t get it right every time. I still occasionally write something dense and clever when what was needed was short and plain. I still sometimes fall in love with an elegant diagram that answers three questions when a reader only needed the answer to one. But I’ve stopped believing that documentation is a chore that sits outside the “real” work of architecture. It’s one of the clearest ways the work of designing a system extends past the moment you finish designing it, and reaches someone you’ll never meet, on a night you won’t be awake for, when they need it most.

If you’re an architect reading this and wondering where to start, I’d say start smaller than feels adequate. Don’t try to document the whole system this weekend. Pick one thing that’s confused someone recently, a service, a decision, a quirk that “everyone just knows,” and write it down as if you were explaining it to a specific person you like, who is tired, who doesn’t have your context, and who you want to spare a bad night. Do that a few dozen times over a year, in whatever spare hour you can find, and you’ll end up with something far more useful than any grand documentation initiative ever produces: a small, honest, growing collection of care, left behind for people you may never get to meet.