If you are new to engineering teams, you will soon hear someone say “that should be in the decision log” or “write an ADR for it.” This primer explains what those phrases mean, shows a real-looking example, and finishes with a mini-glossary so you can follow the conversation. Everything here is deliberately simple: a decision journal for tooling and architecture is a handful of lines, kept in a spot where any teammate can open it.
The basic idea in one paragraph
Whenever your team picks a tool, a pattern or a way of working, write a short note saying what you picked, what else you looked at, why you chose it, and what you expect to happen. Keep the note somewhere permanent. Later, check what actually happened. That is the whole practice. Everything else is detail.
Why beginners should care early
Junior engineers often inherit systems whose design seems arbitrary. Without notes, you can only guess whether an odd choice was brilliant, rushed or accidental. A decision log turns the guess into a lookup. It also trains you to give reasons for your own proposals, which is a skill senior engineers prize highly.
Better still, writing predictions teaches you how good your instincts are. Most newcomers discover quickly that they are optimistic about setup time and pessimistic about the effort of keeping things running. Knowing that about yourself early is a gift.
A small, realistic example
Imagine your team must decide how to ship application builds to a test environment. Here is how an entry might look in a file called decisions.md:
- Date: the day you decided.
- Decision: Use a hosted continuous integration service with a simple pipeline file in the repository.
- Options considered: A self-hosted build server; a hosted service; manual deploys from a laptop.
- Reasoning: The team is small, nobody wants to maintain a build machine, and the pipeline file keeps the process visible in code review.
- Expectation: Every merge produces a test build within ten minutes; fewer “works on my machine” complaints.
- Revisit if: Build minutes become costly or builds routinely take longer than fifteen minutes.
Three weeks later, someone checks: are builds arriving in under ten minutes, and have the complaints dropped? The result goes in a follow-up line.
Where machine learning and operations choices fit
The same format suits data and model work. If you are mapping out how to take a model from notebook to production, a resource like this stage-by-stage plan that machine learning practitioners can follow into production lists the stages. Your decision log records which route you took at each stage and why: which tool to track experiments, how to version datasets, how often to retrain.
For operations teams, a similar log pairs naturally with material on speeding up IT problem resolution with analytics platforms. If you decide to try one, note the specific problem you hope it will ease and a number that would tell you it did.
How a review looks, step by step
Reviews confuse beginners more than writing does, so here is the routine. Open the entry and read the reasoning first, without looking at any results. Ask yourself: given only what we knew then, was this sensible? Next, read your expectation line and check it against reality. Did builds arrive in under ten minutes? Did complaints drop? Write the answer in plain words beneath the original: “Builds averaged twelve minutes; complaints fell.” Finally, decide whether the entry needs a follow-up. If the result missed by a lot, ask what you assumed that was wrong, and say so.
The whole review takes five minutes. Do not skip the first step, because judging the reasoning separately from the result is what stops you from praising lucky choices and punishing unlucky ones.
Mini-glossary
- ADR (architecture decision record): a short document capturing one significant technical decision and its context. The term is common in software teams.
- Decision log: a running list of decisions, usually a single file with entries in date order. An ADR collection is one kind of log.
- Context: the facts and constraints at the time of the decision: deadlines, budget, team size, existing systems.
- Consequence: what follows from the choice, good and bad. Honest entries list both.
- Trade-off: a gain in one area that costs something in another, such as speed versus flexibility.
- Superseded: marks an old entry that a newer one replaces. You never delete the old one; you link forward to the new one.
- Hindsight bias: the habit of feeling, after an outcome is known, that it was obvious all along. The journal exists partly to defeat it.
- Baseline: a measurement taken before a change so you can tell later whether it helped.
Rules of thumb for writing entries
- One decision per entry. Combining two makes each harder to review.
- Write in the present tense of the moment. “We are choosing X because…” keeps the context honest.
- State at least one consequence you dislike. If you cannot name a downside, you have not thought hard enough.
- Add a measurable expectation. Numbers, counts or clear yes-or-no checks work best.
- Never edit history. Add a dated update beneath instead.
Common beginner questions
How big does a decision have to be? If undoing it would take more than a day, or if someone could reasonably ask “why did we do that?”, it qualifies. Renaming a variable does not; changing your database does.
Who writes the entry? Usually the person proposing the change, with teammates adding comments. It works well as part of a pull request.
Where does it live? Next to the code is ideal, because it travels with the project and shows up in searches. A shared wiki page works if you prefer it, provided people actually use it.
What if the decision turns out wrong? Then the entry has done its job. Add an update, explain what you learned, and write a new entry for the replacement. Wrong calls recorded honestly are among the most useful pages in the file.
A brief aside on references you find online
Engineers read widely when making choices, sometimes far outside their own field. You might see how a rental and sharing marketplace for motorbikes and scooters, such as the one at MotoShareGo, presents a central sign-in page, and borrow the idea for your own login screen. Record that in the entry as a reference: “pattern noticed on a consumer marketplace site; adopted in principle.” It costs ten seconds and keeps the source traceable.
Starting this week
Create a file called decisions.md. Add one entry for something you decided in the last month, labelled as written afterwards. Add a fresh entry for the next real choice. Put a review reminder in your calendar. That is a complete beginner setup, which already puts you in front of plenty of experienced groups.
Once the first review lands, you will see the pattern: the log pays for itself not when you write it, but on the day somebody asks “why did we do it this way?” and you can simply point to the page.