Documentation First

The fastest way to settle something is to put the relevant people in a room and talk. That part works. The trouble starts afterward. The decision lives only in the memory of whoever was in the room, and within a few weeks those memories have drifted apart.

So the same discussion happens again. Two months on, one person says the team agreed on option A and another says it was option B with a condition attached. Neither is lying; they each retained a different half of the conversation, and with no record to check, starting over is the only option. It's the same when someone new asks why a thing ended up the way it did. If the person who knew has left the company, the reason left with them.

Documentation first removes the problem by inverting the order. The write-up doesn't come after the discussion; the writing comes before it. The record stops being a by-product of the meeting and becomes its input, which means it survives without anyone setting aside time to preserve it. Notes written after a meeting get skipped when the week is busy. A document written before one can't be skipped, because skipping it means the meeting doesn't happen.

One rule runs the whole thing: if something needs discussing, it gets written first, and only people who have read it join the discussion. In practice there are five steps.

1. Whoever is proposing writes the document. Why this problem is coming up now, what the options are, which one they recommend, and what is still undecided. The last part matters more than it looks. Leave it out and readers have no idea where their opinion is wanted, so they either say nothing or comment on the parts that were already settled.
2. Circulate it with a reading deadline. Without a date attached — read this by Thursday — nobody opens it.
3. Readers leave comments in the document. Factual corrections and mismatched terminology usually get resolved right here. This is the stretch where asynchronous communication, which moves without both sides being online at once, actually does its work.
4. Only the unresolved points get a meeting. With two or three contested items instead of an entire topic, an hour-long session finishes in twenty minutes. If someone shows up without having read, the first ten minutes become silent reading.
5. Write down what was decided and close the document. Three lines will do: what was chosen, why that option, and who does what by when. Skip this step and the previous four were pointless.

What remains after step 5 already has names. A decision record, which captures what was decided and why, is the general form; an architecture decision record (ADR) is the same thing scoped to technical structure, and an RFC is a proposal published openly to collect comments. Documentation first doesn't prescribe which of these to use. It prescribes only that whichever one you use comes before the conversation, not after it.

Three situations are where the practice pays for itself.

1. Teams whose working hours don't overlap. In remote work, where nobody shares an office, the window when everyone is online is two or three hours a day, or nonexistent. Having something to read beforehand is what makes that window usable for discussion rather than briefing.
2. Decisions that will be reopened later. Technical structure and pricing policy are the usual examples — the ones that prompt someone a year out to ask why it was done this way. If the options and the reasons for rejecting them survive, the evaluation doesn't have to be redone.
3. Places where people arrive and leave. When a new hire can catch up by reading past decisions, less time goes into walking them through it, and a handover becomes a list of documents rather than a series of conversations.

There are places it clearly doesn't pay, and they are worth naming because trying to apply the practice everywhere is how teams end up abandoning it. A thirty-second confirmation does not need a document. Neither does a conversation where the difficulty is how people feel about something rather than which option is better. Neither does exploration so early that nobody knows what they would even write down yet. Route any of those through a document and an answer that was two minutes away now takes two days.

"Send a doc around before you book the meeting. Then we'll only talk about what's left."

A request to put the material in writing first so the time together can be shorter.

"That's in last month's decision record. I'll send you the link."

The matter is settled, so read the record instead of reopening it.

"The decision field in this doc is empty. Who's closing it, and when?"

Enough opinions have come in; someone needs to write the conclusion and finish it.

Pagedeck has used this for technical structure decisions since last quarter. When changing the storage approach came up, Theo wrote a two-page document first — what the current structure makes difficult, three options and what each one gives up, and which he recommended — and booked a meeting three days out.

Twelve comments came in over those three days, and eight of them closed with Theo answering in the document itself. The meeting actually covered two of the remaining four. The 45 minutes on the calendar finished in 25, and Mia spent the last five writing the decision and its reasoning at the top of the document. Two months later, when a similar question came up on a different feature, that document stood as the answer.

The most common reading is that this means writing a lot of documents. The name invites it. But what the practice fixes is order, not volume. A team that diligently produces minutes after every meeting writes plenty of documents and is not doing this. Confuse the two and the document count climbs while meeting hours stay flat, and before long someone says all the writing changed nothing and the practice gets dropped.

Hearing it as an argument against meetings is the other one, since it sounds like a call to reduce synchronous communication, where both sides are present at the same time. Meeting counts do fall, but that's a result rather than the goal. The goal is to spend shared time on the points where opinions diverge instead of on briefing everyone. Miss that distinction and teams start skipping discussions that genuinely needed to happen, on the grounds that a document went out — and two weeks pass with the disagreement sitting in forty comments.