You need to sign in or sign up before continuing.
Reflection — An Honest Take 8 min

Honest Take — Before You Begin

Honest Take — Module 3: Documents That Earn Their Place #

Here's what nobody admits about design docs in big-company engineering culture: many of them aren't written to make a decision. They're written to make a decision defensible — insurance for the author against the manager asking "why did you do it this way?" six months later. The thinking happened in someone's head; the doc is the audit trail with reviewers signed in. This is cynical and partly true, and I tell you because it clarifies what the genre is for when the politics are stripped away. If you're a maintainer, a founder, or an engineer at a small company, nobody is going to make you write design docs. The forcing function is internal. Which means you get the genre's honest purpose — actually thinking through the design before committing — without the defensive overhead. That's a privilege. It also means you have to want the discipline for its own sake, because it makes the design better, not because it makes you safer. Cleaner motivation; rarer one.

The truth most engineers learn the hard way: writing the design doc is the part where you discover the design is wrong. They go in thinking "I have the design, I just need to write it up," and come out four hours later having rewritten the proposal section three times, because explaining it revealed two assumptions that didn't hold. That painful afternoon is the value of the doc. The doc is a thinking tool first, a coordination tool second, a defense tool third — and most engineers experience the three in reverse order. The corollary is uncomfortable: the more senior you get, the more your value moves into the documents, and you'll wonder whether you're still "really engineering." You are. The design doc that prevents a six-month boondoggle is satisfying for nobody, because the boondoggle never happens. Learning to recognize non-events as wins is one of the hardest psychological adjustments on the staff-engineer track.

The two earlier drafts of this curriculum centered different artifacts, and the merge keeps both on purpose. One built this module around the working genres — README, RFC, ADR, postmortem — the documents that run engineering teams day to day. The other treated the Amazon-style six-page narrative memo as the centerpiece: a real decision argued in connected prose, read silently at the top of the meeting. The memo discipline earns its place for one reason — slide decks let bad arguments hide between bullets, and a six-page narrative cannot hide. Every claim has to live in connected prose where the joints between claims are visible. You'll recognize the difference as the difference between reviewing a full feature and reviewing a one-line diff: the connected form forces the author to defend the structure, not just the surface. Write one real memo about one real decision, then have someone read it cold and tell you what they took away. The gap between what you wrote and what they understood is the actual learning. By the fourth memo the gap is small, and you will never again build a slide deck when a memo would do.

If you maintain anything public, the README deserves its own paragraph, because it is the highest-stakes page of writing you own — read by a stranger at 11pm with three minutes and no context, deciding whether your project deserves a fourth minute. The exercise that recalibrates fastest: read three competitor READMEs cold, then re-read yours, then ask whether yours closes the deal in the first scroll the way you assumed it did. You'll find one or two fixes. The more interesting finding is what the exercise teaches you about the next project's README, written before anyone is watching.

And do the retroactive ADR, even though it's the checkpoint item you'll most want to skip. Writing down a decision you already made — already in production, already working — feels like pure overhead. It isn't. It's a one-person retrospective: what you were thinking, what you weren't thinking about, what you'd decide differently now. The discipline of doing this regularly is what turns ten years of experience into ten years of learning, instead of one year repeated ten times.

A word on the genre I haven't mentioned: the postmortem, which is the political document wearing a technical costume. The first one you write about your own production failure will be defensive — every sentence quietly arguing that the failure was reasonable — because it's your system and the document feels like testimony. That one will be bad, and that's fine. The craft is learning to write it for the readers who weren't there: what happened, in timeline form; what the system and the humans did with the information they had; what changes, specifically, with owners. Blameless is not a tone, it's a discipline of attribution — causes live in systems and incentives, not in characters. By your fourth postmortem you'll be writing them the way senior engineers do: as the cheapest organizational learning available, even when the organization is just you.

Conclusion #

Lean into the genres — README, design doc, ADR, postmortem, memo — instead of inventing your own structures; the genres encode decades of institutional learning about what readers in your absence need. The fastest way to find out if your design is wrong is to write the design doc. The fastest way to make the why survive is the ADR. The fastest way to find out whether your thinking holds is six pages of connected prose and a cold reader. All of them are short documents that prevent long mistakes.

Predictions #

  • The README rewrite will be the checkpoint item you do first — most concrete, most visible payoff. Correct sequencing; enjoy it.
  • The retroactive ADR will be the item you put off, then begrudge, then find unexpectedly clarifying. You'll come out of it deciding to write one or two ADRs prospectively for upcoming decisions. That's the win.
  • The design doc for a live decision will, mid-draft, surface a problem you didn't know the design had. Don't be discouraged — that is the doc working, and it's cheaper to meet the problem on the page than in production.
  • The memo will feel pretentious for the first thirty minutes. By the second one you'll prefer it to slides for any decision that matters, and within a month you'll catch yourself in a meeting that should have been a memo and feel the absence physically.
  • Within three months, you'll notice a missing Alternatives Considered section in someone else's doc and say so. You'll feel mildly self-conscious about being That Person. Be That Person; most teams need exactly one.
  • You will not maintain the quarterly doc-review cadence. Almost nobody does until one doc-rot disaster makes the case. Skip it and pay the tuition if you must — but know the bill is coming.