Every project we take on at PhonedTech, even a small one, comes with at least one short written note about a big decision. One page, in plain language: what we decided, what else we considered, and why. (Software teams call these “architecture decision records”.)
We’ve been writing them for years. It’s the most boring thing we do. It also saves more time than anything else we do.
Here’s what goes into these notes, when we write them, and why they matter to you as the owner of the system, not just to the people who build it.
Why a business owner should care
Building software means making a lot of choices. Some are small and easy to change later. Others are hard to undo: which supplier to sign with, how your customers log in, where your information is kept.
Those big choices affect the cost of everything that comes after. And a year later, someone always asks: “Why did we do it this way?”
If the answer lives only in one person’s head, you have a problem. That person may have left. You may have moved to a different software company. An investor, or someone who wants to buy your business, may ask. Without a written answer, people guess, argue or start again, and you pay for it.
What goes on the page
Each note has four short parts and fits on one printed page:
- The situation: what was going on, and what limits we had, such as budget, deadline or the tools you already use.
- The decision: what we chose, in one sentence.
- The other options: what else we looked at, and why we said no to each one.
- What it means for you: what becomes easier, what becomes harder, and what we should look at again later.
That’s all. No required diagrams, no forms to sign, no long approval process. One person writes it. The rest of the team reads it and comments, just like any other piece of work.
When we write one
There are three moments. Any one of them is enough.
When the decision touches more than one part of your business. Choosing where one small part of your system keeps its information is an everyday choice. Choosing where your website, your app and your reports all keep their information deserves a page.
When the decision is hard to undo. Signing with a supplier. Choosing how customers log in. Deciding whether all your customers share one system or each gets their own. Choices like these change the cost of every future project. Whoever works on your system later will want to know why.
When people disagreed. If two senior people argued for an hour, we write down what was decided. Otherwise the same argument comes back six months later, sometimes after one of them has already left.
What it isn’t
It isn’t a full plan for how to build something. A plan explains how. This note explains why we chose this way and not another. The plan is mostly for the people building the system. The note is for anyone who asks “why?” later, and it stays useful for as long as the system is in use.
It also isn’t something we keep rewriting. If a decision changes, we don’t edit the old note. We write a new one, say which note it replaces, and link the two. Over time, you get a simple history of why your system works the way it does.
What it actually saves you
You won’t see the value in week one. You’ll see it in month nine, when someone new joins and asks, “Why did we pick this system and not that one?” The answer is already there, on one page that took a few minutes to write.
Now multiply that by every new employee, every new supplier and every outside expert, for as long as your system is in use. In practice, it means:
- No paying for the same argument twice. Settled questions stay settled, unless something real has changed.
- Faster starts for new people. A new developer, or a whole new team, reads the reasons instead of guessing them.
- Easier second opinions. If you ever ask an outside expert to check your system, they can see why things were done, not just what was done.
- Less dependence on any one person. That includes us.
Part of owning what you paid for
From day one, the code, the cloud account and your web address (domain) are in your company’s name. These decision notes stay with them, together with written notes on how everything works. So you can move the work to your own staff, or to another team, without starting again.
We don’t disappear after launch. If you like, we keep your system updated, backed up and running smoothly. That part is up to you. And if you ever decide to move on, the reasons behind every big decision stay with you.
Questions to ask any software team
Whether you work with us or with someone else, these are fair questions to ask before you sign:
- When you make a big choice for us, will you write it down? Where will we find it?
- Will it be in plain language that I can understand without a technical background?
- If we change teams one day, what will the new team get from you?
- Will the code, the cloud account and the domain be in our company’s name?
If the answers are vague, ask again. It’s your business. You should be able to understand why it works the way it does.
Planning a new system, or trying to make sense of one you already have? Book a free 30-minute call and tell us what’s going on. We’ll give you an honest view and send you a short written summary, even if we don’t end up working together. You can also read more about our custom software development service, or about CTO as a service: a senior tech partner, part-time, who helps you make decisions like these.