Someone asks why the company’s domain name sits in a web designer’s account, or why customer data lives where it does, and nobody can say. Either the person who chose it left or they’ve forgotten, and the reasons went with them. You’re then left guessing whether the choice was deliberate, whether it still holds, and what it’d cost to change.
A short written record at the time of the decision stops that happening. It doesn’t need a process, a template library or a tool. It needs one page, written while the reasons are still fresh.
Which decisions deserve a page
Most choices don’t. Picking a mouse or a font isn’t worth recording. The ones that are tend to be hard to undo, expensive when wrong, or likely to be questioned by someone who wasn’t in the room. That’s a long list for a young organisation (our Startup services page describes how we work with them), and it usually includes where your data lives, which platform you build on, who owns your domain and accounts, how you connect two sites, which supplier you tie yourself to. A good test is to ask whether a new colleague, a year on, would reasonably ask “why on earth did we do it this way?”.
The idea of writing these down isn’t ours. Michael Nygard described architecture decision records in 2011 as short notes, each with a title, a context, the decision, its status and its consequences, kept alongside the work and never deleted, only marked as replaced. He suggested one or two pages. What follows is our adaptation of it for people who aren’t writing software.
What goes on the page
Start with the context: what’s going on, what pressure you’re under and what you know. Write it as plain facts. “We’re hiring four people by June and have no shared storage” is useful. “We need a great solution” isn’t.
Next come the options you seriously considered, including doing nothing, each in a line or two with its main strength and its main weakness. This is the part that’s easiest to skip, and it saves the most time later, because it stops the same idea being rediscovered and proposed again as if it were new.
Then the decision itself, in a sentence or two, starting “We will…”. After that, the consequences, good, bad and neutral. Be honest about the downsides you’re accepting. If a choice has no downsides on the page, someone hasn’t thought about it hard enough.
We’d add two things Nygard’s outline doesn’t spell out. One is who decides, and who was consulted, so a record isn’t an orphan. The other is a date or a trigger to revisit it: a month in the diary, or an event such as “if we pass thirty staff” or “when the contract renews”. Without it, a decision quietly becomes permanent by default.
An illustration, with made-up details
Here’s a short example, invented for this article and not drawn from any client. A twelve-person company finds its domain name was registered years ago by a web designer, who still holds the account.
Context. The domain carries the company’s email and website. It’s registered in an outside person’s account, so the company has no way to renew it or change where it points without asking them.
Options. Leave it, since it works as it is. Ask the designer to transfer it to an account the company owns. Register a new domain and migrate, which is cleaner but means changing every address the company has ever published.
Decision. The company will ask for a transfer into an account owned by the company, with two named people able to sign in.
Consequences. Someone has to watch renewals, and the renewal reminders go to a shared mailbox rather than one person’s inbox. There may be a short wait while the transfer completes. No published address changes.
Who and when. The managing director decides; the office manager was consulted. It will be looked at again at the next renewal, or sooner if the company changes email provider.
Notice what it does. It’s about ten sentences, and anyone arriving later can see what was weighed and who to ask. Real records for bigger choices run longer, but if one spills well past a page, you’ve probably bundled two decisions together.
Keeping it light
The habit survives only if it’s cheap. Write the record on the same day as the decision, in the time it takes to explain the choice to a colleague, and it needn’t take long, often about a quarter of an hour. Leave it a month and it turns into archaeology.
Keep every record in one place the whole team can read, such as a shared folder or a wiki, and give each a date and a status. If a decision is reversed, don’t edit the old page. Write a new one that says what changed and why, and mark the old one as replaced, which is how Nygard handled it too. The history is half the value.
Resist the urge to write a record for every choice, or to polish them. A rough page that exists beats a good one you never wrote. And if you’re a small organisation, a single shared document with the records one after another works fine until it gets unwieldy. If one of the choices is technical enough that you can’t judge the options yourself, that’s the moment to get an independent person to read the page before you commit, because that’s when a second opinion costs least.
If you’re unsure whether a choice you’re facing is big enough to deserve a page, or you’re close to committing to something that would be hard to unpick, you’re welcome to write to us before you decide.