Architecture Decision Records for Data Teams: Making Trade-offs Explicit
A decision record is a page that says what was chosen, what else was considered and what the choice will cost. Its value is realised later, by someone who was not in the room and has to decide whether the reasoning still holds.
A data team chooses a table format in a meeting, a partitioning scheme in a chat thread and a modelling convention in a pull request. Months later a new architect asks why the warehouse is loaded the way it is, and the answers are a guess, a shrug and a name of someone who has left. The choice is then either defended without reasons or reversed without understanding, and the argument that was settled once is held again.
An architecture decision record, or ADR, is the lightest practice that prevents this. This article is about using it well in a data team: which decisions deserve a record, how to write the options and the consequences so that they are worth reading, who decides, how a record is replaced, and the ways the practice goes wrong. The published guidance was written for software teams. DII applies it to data architecture by analogy, and says where the fit is imperfect.
A short page with a fixed shape
The format comes from a 2011 article by Michael Nygard, which the UK Government Digital Service describes as “since adopted widely”1. His starting observation was about what gets lost: “One of the hardest things to track during the life of a project is the motivation behind certain decisions”2. Without the motivation, a newcomer can only accept a past decision blindly or change it blindly, and Nygard’s judgement was that “It’s better to avoid either blind acceptance or blind reversal”2.
His answer was a short text file with five parts: a title, the context, the decision, its status and its consequences. Two instructions in the original are easy to skip and carry much of the value. The context is to be neutral: “The language in this section is value-neutral. It is simply describing facts”2. And the length is capped: “The whole document should be one or two pages long”2.
The brevity is deliberate. Nygard’s argument against the alternative is blunt: “Large documents are never kept up to date”2. A decision record is not an architecture document. The UK Government Digital Service makes the same point in its engineering standards: “An ADR isn’t a complete description of a software system or architecture”1. It is one decision, with its reasons, dated.
Which decisions deserve a record
Recording everything turns the practice into a chore. The sources converge on a threshold. Nygard reserves records for decisions “that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques”2. Microsoft’s architecture guidance offers a shorter test, and the last clause is the most useful: “Only include choices that affect the system’s structure, key quality attributes, or are difficult to reverse”3.
For a data team, difficulty of reversal is the practical filter. The table applies it to choices a data team actually faces. The classification is DII’s.
Which data decisions warrant a record
| Decision | Record it? | Why |
|---|---|---|
| Warehouse, lake or lakehouse as the main analytical store | Yes | Shapes cost, skills and every later choice; takes a migration to undo |
| Open table format, and which one | Yes | Fixes which engines can read the data and how it is maintained |
| Transform before loading or after | Yes | Determines where logic lives and who can change it |
| How customers, products or accounts are identified across systems | Yes | Every join depends on it; changing it rewrites history |
| Which team owns a shared dataset | Yes | An ownership boundary, costly to move once consumers rely on it |
| Retention period for a raw data zone | Yes | Deleted data cannot be recovered; kept data carries cost and risk |
| Naming convention for tables | A team standard, not a record | Worth writing down once; cheap to revise |
| Which chart library a dashboard uses | No | Local and easily reversed |
| How one pipeline handles a late file | No | An implementation detail, visible in the code |
The pattern comparisons that produce the first rows are covered in data warehouse, data lake or lakehouse and ETL vs ELT: how to choose for your workloads. A record is where the outcome of that reasoning is kept.
One difference from software deserves a note. In an application, a reversed decision means changing code. In a data estate it can also mean reprocessing years of stored data, or accepting that history before the change is not comparable with history after it. That raises the cost of reversal for data decisions and lowers the threshold at which a record is worth writing.
Stating the options honestly
Nygard’s original format has no section for alternatives. Later guidance adds one, and DII regards it as essential. Microsoft’s list of what a record should contain begins with the problem and continues with “Options considered” and the “Decision outcome”, and says a record should cover “alternatives that you ruled out”3.
The test of an options section is whether a supporter of a rejected option would recognise their case in it. Three habits help.
Describe each option at its strongest. An alternative written as a caricature tells the future reader only that the author had already decided.
Name the criteria before scoring anything. Cost to run, fit with existing skills, time to first use, ease of leaving. If the criteria were chosen after the favourite, it will show.
Say what was not known. Microsoft’s guidance includes an instruction worth following: “Record the confidence level of the decision”3. A choice made on a two-week trial, with one workload, is a different thing from one made after a year in production, and the record should let a reader tell them apart.
The title matters more than it appears to. The GDS standard asks for “a description of the decision (not the problem)”1. A record headed with the decision itself, for example that customer events are stored in an open table format, can be found and understood from a list. One headed only with its topic, storage, cannot.
Consequences are the part that earns the record
A record that lists only benefits is an advertisement. Nygard asks that every consequence be listed, including the ones that are not positive2. Microsoft’s guidance is sharper about the temptation: “Avoid hiding consequences of decisions intentionally or accidentally”3.
For data decisions, the consequences worth forcing onto the page are the ones that fall on someone else. A choice to load data raw and model it later is quick for the team that loads and slow for each team that reads. A choice to standardise on one engine saves licences and removes an option some analysts relied on. A useful discipline is to ask, for each consequence, who bears it, and to write down the name of a team.
The AWS guidance on the practice identifies why this section carries the weight. The strength of the format, it says, is that “it focuses on the reason for the decision rather than how the team implemented it”4. Implementation can be read from the code and the pipelines. Reasons and accepted costs exist nowhere else.
Who decides, and who is consulted
The format is silent on authority and that silence causes trouble. A record needs one accountable author. AWS’s description of the process puts it this way: “Every team member can create an ADR, but the team should establish a definition of ownership for an ADR”4.
Review should be wide enough to catch what the author cannot see. GDS states the requirement in a sentence: “It’s important to find the right group of reviewers for your ADR”1. For a data decision that group reaches beyond the data team: the people who run the source systems, the consumers who will bear the consequences, security, and whoever pays the bill.
Review does not have to be heavy. AWS describes a meeting that opens with everyone reading the record in silence, and puts a figure on it: “On average, 10 to 15 minutes should be enough”4. The outcomes are acceptance, rework or rejection. A rejected record is kept, and the guidance gives the reason: “the ADR owner adds a reason for the rejection to prevent future discussions on the same topic”4. A decision not to do something is as much worth finding later as a decision to do it.
What the published guidance does not settle is who has the final say when reviewers disagree. That depends on the organisation. DII’s advice is to name the decider on the record itself. A record with five reviewers and no decider documents a discussion.
Replacing a decision without rewriting it
Decisions change. The discipline is to change them in the open. Nygard set the rule at the start: “If a decision is reversed, we will keep the old one around, but mark it as superseded”2. AWS states the principle more strongly: “When the team accepts an ADR, it becomes immutable”4.
The GDS standard adds a practical distinction. A decision that was never acted on can be amended. Once work has been done, the standard says, “you should write a new ADR to explain the new decision”1. The old record stays, marked as superseded and linked to its replacement.
This is what makes a set of records a history. A reader can see that the team chose one approach in one year for stated reasons, and another later because a stated circumstance changed. An edited record shows only the latest position and invites the question of what else has been tidied.
How the practice fails
The format is simple, so when the practice fails the template is not the place to look. Four patterns are worth guarding against. They are DII’s observations from the logic of the practice and from the cautions in the sources. They are not findings from a study.
Ceremony. Every choice gets a record, records need sign-off from a board, and the board meets monthly. Teams respond by deciding first and documenting when forced. The remedy is the threshold above, and a review measured in minutes.
Retrospective justification. The record is written after the decision, to defend it. The options section then describes alternatives nobody seriously weighed. Microsoft’s guidance does allow records to be reconstructed for existing systems, “retroactively generated based on known past decisions”3, and that is legitimate when the record says so. The failure is presenting a reconstruction as a deliberation.
Records nobody can find. A decision filed in one team’s repository is invisible to the team it constrains. GDS warns that teams “may need to know about its existence long into the future” and asks authors to think about how records are discovered1. For decisions that cross teams, a single index is worth more than a perfect template.
Decisions that are recorded and not carried out. The record says one thing and the estate does another. The GDS standard closes its section on implementation with a line that applies to every team: “The work isn’t done until the decision is implemented!”1. Microsoft describes the cost of the opposite failure, the decision that is made and never recorded: it “will likely be forgotten, leading to repeated debates or later changes that unknowingly contradict the original intent”3.
Starting with what you already have
A team does not need a programme to begin. Three steps are enough.
First, write records for the three or four standing decisions that keep being questioned, and label them as reconstructions. The seven decisions described in modern data architecture: the layers, patterns and decisions that matter are a reasonable list of where to look. Second, agree the threshold and the decider. Third, write the next real decision as a record before it is made, and use the review to make it.
The Data Architecture Decision Framework supplies the structure: context, options against stated criteria, decision, consequences by affected party, confidence, decider and status. The Architecture Review Checklist is the companion for checking a design before a decision is taken.
Two places where records pay for themselves are a platform selection, where the reasoning will be asked for by finance and by the next architect, as discussed in how to evaluate and select a data platform, and an architecture review, where the records are the first evidence a reviewer should ask to see. Running a data architecture review that changes something takes up that use.
Sources
- Government Digital Service (UK). Documenting architecture decisions (The GDS Way). Updated 5 March 2026.
- Nygard, M. Documenting Architecture Decisions (Cognitect blog). 15 November 2011.
- Microsoft. Maintain an architecture decision record (ADR) (Azure Well-Architected Framework, Microsoft Learn). Updated 13 April 2026.
- Amazon Web Services. Architectural decision record process (AWS Prescriptive Guidance).
This article is general professional information. It is not legal or regulatory advice.