The Documentation Nobody Writes
The README gets written. The API docs get written. The inline comments get written, sometimes. Nobody writes down why the architecture is the way it is, and six months later nobody knows. Including the person who made the decision.
This is the documentation gap that actually costs teams time. Not missing function signatures — those are annoying but recoverable. Missing decision rationale is the one that causes real damage, because it means every architectural decision has to be reverse-engineered from the code, and the code doesn't tell you what was considered and rejected.
What Decision Documentation Looks Like
Architecture Decision Records (ADRs) are the standard answer, and they're good. The format is simple: context, decision, consequences. What was the situation, what did we decide, what are the tradeoffs we accepted. A paragraph each. Takes ten minutes to write when the decision is fresh. Takes hours to reconstruct six months later.
The systems thinking approach to this is to treat documentation as part of the decision process, not as something you do after. Writing the ADR before you implement forces you to articulate the tradeoffs, which sometimes reveals that the decision isn't as clear as you thought.
The Decisions That Need Documentation Most
Not every decision needs an ADR. The ones that do are the ones where you chose between two reasonable options, where you accepted a known tradeoff, or where you're doing something that looks wrong but isn't. Those are the decisions that will confuse future you and future teammates.
The "looks wrong but isn't" category is especially important. If you have a piece of code that looks like a bug but is actually intentional behavior, document it. Not just with a comment — with an explanation of why the seemingly-wrong thing is correct. Future developers will try to fix it. They will break things. This is preventable.
The josephcalitoy.com writing on invisible work is relevant here — the decisions that don't make it into the visible output but shaped everything about it.
The Tooling Question
ADRs work best as markdown files in the repository, versioned alongside the code. Some teams use wikis. Some use Notion. The format matters less than the habit. The habit is: when you make a significant architectural decision, write it down before you implement it.
The technical decisions archive has some material on how to build this habit into a team's workflow without it becoming bureaucratic overhead.
More on developer culture and building at Opened Terminal.