How to document engineering decisions (without a process nobody follows)

Record the why, not the what

The code, the config, and the architecture diagram already say what you built. The only thing a future reader cannot recover on their own is why: the constraint that forced the choice, the alternatives that lost, the tradeoff you knowingly accepted. If you write down one thing, write that. A single honest sentence - “chose X over Y because Z; accepting W” - beats a page of restated implementation.

Capture at the moment of decision

Context has a half-life measured in days. The version written the afternoon a choice is made includes the alternatives and the doubts; the version reconstructed two months later is a rationalization of whatever got built. Make the record part of closing the decision - the last comment in the discussion, the merge of the proposal - never a cleanup task for later. “Later” is where documentation goes to die.

Keep it where work already happens

A separate documentation system is a place nobody visits. Records survive when they live in the tools the team already touches daily: an ADR folder in the repo, a decision label in the issue tracker, a pinned summary comment on the pull request that settled the argument. The test is retrieval, not storage: when someone asks “why is it like this?”, is the answer one search away in a tool they already have open?

The anti-patterns that kill adoption

• The heavyweight template. Twelve required fields produce zero filled-in records. Every field must earn its place; five is plenty.
• The documentation sprint. Backfilling history in one heroic push produces records nobody trusts and burns the team on the practice. Start from today, going forward.
• The single owner. If one person is “the documenter”, the practice leaves when they do - which is exactly the failure it was meant to prevent. Whoever drives a decision records it.
• Write-only records. If records are never cited in onboarding, review, or debate, the team correctly concludes they do not matter. Link to them when settled questions resurface - that is the payoff loop that sustains the habit.

Accept the gap - then close it

Run this practice well and an honest fraction of significant decisions still goes unrecorded: they happen inside ticket threads, review comments, and meetings, where nobody thinks “this is a decision” until much later. The discipline above shrinks the gap; it cannot close it, because closing it by hand means asking humans to notice every decision in real time. This is the part Rationale automates: it reads the artifacts your team already produces - tickets, docs, pull request discussions - finds the decisions inside them, and maintains the reasoning as a connected, current Decision Map, so the practice you run and the record you keep stop being the same size.