Why we write every decision down

Every software project takes hundreds of decisions. Almost all of them are small, but a few shape everything else: what it is built with, where the data lives, how it connects to your other systems, what is left for later. In many projects those decisions live only in the head of whoever took them. We write them down.

What a written decision is

It is a short document, a page or less, that answers three questions:

• What we chose. For example: “The website will have a content editor so your team can change the copy.”
• Why. “Marketing changes the copy every week, and we do not want them to depend on us for that.”
• What we ruled out, and why. “Editing the copy in the code itself: cheaper at first, but every change would go through us.”

It is in your language and in plain words, because it is meant for you to read, not only for another programmer.

What it saves you

The same discussion twice. Six months later, someone asks why it was not done another way. The answer is already written, with what was known at the time. If circumstances have changed, it shows at once, and the decision is taken again on judgement, not on a hunch.

Depending on one person. If the project changes hands, because your team grows or because you decide to work with another provider, whoever arrives understands in an afternoon what took months to decide. Without those documents, the new team usually proposes to rebuild everything, because it cannot tell why things are the way they are.

Surprises in the cost. When a decision has alternatives, we write them down with what each one costs. You decide, knowing what you gain and what you give up.

Why it is yours

Once paid for, the code is yours, and so are the documentation and these decisions. That is what lets you stay with us because you want to, not because nobody else understands your system.

What it looks like in practice

Before building anything important, we walk you through the options and their cost, and we decide together. That conversation ends in a written decision, which you can read whenever you like in your project’s tracking space. If something changes later, it is not erased: a new one explains what changed and why, and the old one stays as history.

It is a small habit that cannot be seen from outside, like the roots of the retama, the broom shrub that holds on in poor soil thanks to a root far deeper than the plant is tall.