Your codebase is documented. Your decisions aren't.

Most well-run engineering teams have reasonable code documentation: comments, READMEs, API docs, type signatures, and docstrings. The code itself serves as a form of documentation for what the system does. A competent engineer reading the codebase can understand the current behaviour of any component.

What they can't understand from the code alone is why.

Why is the auth service a separate microservice rather than a module in the monolith? Why does the data pipeline use batch processing instead of streaming? Why is this particular library used for HTTP requests when a more popular alternative exists? Why does the schema have a column called legacy_status that's populated but never read?

Each of these questions has an answer, and that answer was discussed, debated, and decided at some point in the past. The discussion probably happened in a Slack thread, a meeting, or a PR comment. The decision was made, the code was written, and the reasoning evaporated.

The cost of missing decisions

When the reasoning behind a decision is lost, two things happen.

New engineers make mistakes the team has already made. An engineer who doesn't know why the auth service is separate from the monolith might propose merging them, spend a week building a proof of concept, and then learn in a review that the separation exists because of a latency issue discovered the hard way two years ago. The week was wasted because the reasoning wasn't documented.

Resolved decisions get relitigated. Someone raises the question of batch vs streaming for the data pipeline. The team spends a meeting debating it. Halfway through, someone remembers that this was discussed a year ago and the conclusion was that streaming would require infrastructure changes that weren't worth the latency improvement. The meeting was wasted because the previous decision and its reasoning weren't findable.

Both of these costs are invisible in the moment (they look like normal engineering discussion) and enormous in aggregate (the same decisions debated multiple times, the same mistakes repeated by successive engineers, the same context reconstructed from scratch whenever someone new encounters the system).

What decision documentation looks like

A decision document doesn't need to be elaborate. The essential elements are:

The question. What was being decided? Framed as a clear, searchable question.

The options considered. What alternatives were discussed? Even a brief list is valuable because it shows that the current approach was chosen rather than defaulted to.

The decision. What was chosen?

The reasoning. Why was this option selected? What trade-offs were accepted? What would need to change for the decision to be revisited?

The date and participants. When was this decided and who was involved?

This format is sometimes called an Architecture Decision Record (ADR), and teams that use it consistently report significant reductions in decision relitigation and onboarding friction.

The automation angle

The challenge with decision documentation is the same as with all documentation: it requires someone to write it, and the moment of decision is rarely the moment anyone feels like writing a document about it.

Self-writing documentation can capture decisions from the sources where they're actually made. A Slack thread where the team debates two approaches and reaches a conclusion can be automatically summarised as a decision record. A meeting where architecture options are discussed can produce a structured document from the transcript. A PR description that explains a non-obvious design choice can be linked to the broader decision history.

The decisions are already being made. The discussions are already happening. What's missing is the capture, and automated capture from the existing channels is far more reliable than asking engineers to write up their decisions after the fact.

Frequently asked questions

Isn't this overkill for small decisions? Not every decision needs a formal document. The threshold: if you'd expect a new engineer to ask "why is this done this way?" when they encounter it, the reasoning should be documented. Decisions about fundamental architecture, technology choices, and significant trade-offs almost always qualify.

Where should decision docs live? Alongside the system documentation, searchable and linked to the relevant code or system. A decision log that's separate from the engineering wiki is better than nothing but less useful than decisions that are integrated with the system documentation they relate to.

How do we retroactively document past decisions? Start from the decisions that cause the most friction: the ones that get relitigated most often or that new engineers most frequently ask about. Write up the reasoning from the people who remember it, and accept that older decisions may need to be marked as "reconstructed" rather than definitive.

Related reading: The bus factor, The hidden cost of tribal knowledge, Documentation debt. Related pages: Self-writing docs, Decision log, For engineering teams.