We had a documentation problem. Not the kind where nobody writes anything — we had docs. The problem was subtler: we were documenting the wrong things at the wrong time, and everything we wrote was outdated by the time someone needed it.
The shift that fixed it wasn't a new tool or a new policy. It was a single habit change that took about a week to stick and has compounded ever since.
What we were doing wrong
Like most teams, we wrote documentation after the fact. After a feature shipped, someone would write a guide. After a process was established, someone would write a runbook. After an incident was resolved, someone might write a post-mortem if they had time. The docs were always written from memory, usually by whoever had the most context, usually when that person had a window, which was rarely the same week the work happened.
The result was documentation that was accurate about what happened three months ago but didn't reflect the current state of things, written in a tone that assumed the reader had context they didn't have, and stored in a location that made it hard to find unless you already knew it existed.
We had a wiki. It had about four hundred pages. Almost nobody consulted it for practical answers because the signal-to-noise ratio was low. Finding something useful required enough prior knowledge to know what to search for.
The shift: document the decision, not the outcome
The change we made was this: stop documenting what we built, and start documenting decisions as we made them. Not a retrospective summary. A brief note at the moment a decision was made: what we decided, what we considered, what we rejected and why, what assumptions we're making that could turn out to be wrong.
We call these decision notes. They're not formal. They're not designed for external audiences. They're the kind of thing you'd write in five minutes before you moved on to the next task. The discipline is in the timing: you write it when the decision is fresh, before the context exists only in one or two people's heads.
A decision note might look like: "We're going with the polling approach instead of webhooks for now. Webhooks would be cleaner long-term but require vendor support we don't have yet. This is explicitly a temporary choice — revisit when we add the second integration partner." That's it. Written in three minutes. Attached to the project workspace where the related work lives.
Why the timing matters so much
Documentation written at the moment of decision is categorically different from documentation written after the fact. At the time of the decision, you know:
- What alternatives you actually considered (not just the one you chose)
- Why you rejected the alternatives (the real reasons, not the polished post-hoc reasons)
- What information you had at the time vs. what you wish you'd had
- What you're uncertain about and what you're confident in
Three months later, you know the outcome. But the reasoning is fuzzy, the alternatives are forgotten, and the person who made the call has moved on to other things. You can write a prettier document, but it's less useful.
The compound effect over time
The first month we did this, it felt like we were generating a lot of small notes that didn't seem particularly valuable on their own. By month three, something had shifted. New team members were getting up to speed faster, not because we'd created better onboarding materials, but because the accumulated decision notes gave them a real picture of how and why the product had evolved.
Questions that used to require tracking down a specific person could now be answered by searching the workspace. "Why do we do it this way instead of the obvious way?" often had a decision note attached to it. The note might say "we tried the obvious way and here's why it didn't work." That's information you can't get from documentation written after the fact.
The other change was in our meetings. When a decision came up that we'd made before, someone would find the note and share it. Half the time the reasoning still held. When it didn't, the note at least told us why we'd made the original choice, which made it easier to evaluate whether the situation had changed enough to justify changing course.
What didn't work
We tried to apply this everywhere first, and it was too much. Not every decision needs a note. "We'll ship this on Thursday" doesn't need to be documented. The habit works best for decisions with a longer half-life: architectural choices, process changes, product direction shifts, hiring decisions. Anything where someone in six months might reasonably ask "why do we do it this way?"
We also had to fight the instinct to over-format. Early on, people were spending too long writing polished decision notes instead of useful ones. The format that works is: one sentence on what was decided, one or two sentences on why, one sentence on what wasn't chosen and the main reason. That's usually enough. If there's more nuance, it can be longer. But the minimum viable decision note is four sentences.
One habit, significant change
The teams that treat documentation as a project — something you do after things are done, when there's time, to create artifacts — always have a documentation problem. The teams that treat it as a habit — a small thing you do while work is happening, attached to the work itself — tend not to.
The tool doesn't matter much. A shared doc, a workspace note, a comment on a project card. What matters is that it happens at the moment of decision and ends up somewhere attached to the project it belongs to.
Four sentences. Right now. Before you move on.