The problem: results without reasons
Most documentation describes what a system is. Far less describes why it is that way. A year later, someone finds an odd arrangement: a component that seems oversized, a process that seems roundabout, a library that seems an odd choice. Nobody remembers the reason. Either the choice is left alone out of caution, or it is changed and the original problem returns.
A design decision record, sometimes shortened to DDR (some teams call similar documents architecture decision records), is a short note capturing one significant decision: what was decided, why, and what else was considered. It is a snapshot of the thinking at the time, not a living description of the system.
What counts as a decision worth recording
Not every choice needs a record. A reasonable filter is to write one when a decision is:
- costly or slow to reverse, such as a choice of platform, interface or material;
- the result of weighing real alternatives, where reasonable people could have chosen differently;
- likely to puzzle a future reader;
- affecting several people or teams;
- tied to a constraint, such as a regulation, a budget or a supplier limit, that is not visible in the finished work.
Small, easily reversed choices do not need this treatment. A team that records too many decisions will find the records neither read nor maintained.
What a record contains
Formats vary, and the content matters more than the template. A compact record often has these parts.
- Title. A short phrase naming the decision, such as “Use a standard connector for the sensor cable”.
- Status. Proposed, accepted, or replaced by a later record. Status tells the reader whether the record still stands.
- Date and people. When it was made and who took part, so that readers know whom to ask.
- Context. The situation and the forces at play: the requirements, constraints, deadlines and unknowns. This is often the most valuable part, and the part most easily lost.
- Options considered. The realistic alternatives, including the option of doing nothing, each with its main strengths and weaknesses.
- Decision. What was chosen, stated plainly.
- Reasons. Why this option was preferred over the others, in terms of the context above.
- Consequences. What follows: benefits expected, costs accepted, risks, and anything that will need to be done or watched afterwards.
For many decisions, half a page is enough. If a record is much longer, the extra material may belong in a separate analysis that the record summarises.
An illustration
The following is an invented, simplified example to show the shape, not a recommendation about any real design.
Title: Store calibration data in a separate file. Context: Calibration values differ for each unit and are updated at the end of production. The main program changes more often than the calibration values do. Options: (1) Build values into the program; (2) keep them in a separate file loaded at start-up; (3) read them from the device itself. Decision: Option 2. Reasons: It lets calibration be updated without rebuilding the program, and it avoids depending on a device feature that the team has not yet tested. Consequences: The program must handle a missing or damaged file. The file format needs to be documented.
Even this short note would tell a future maintainer both what was chosen and what to be careful about.
Recording tradeoffs honestly
The value of a record lies in showing the tradeoff. Almost every real decision gives something up. Writing the downsides down, and not only the advantages, makes a record trustworthy. It also helps later readers judge whether the conditions have changed. If the reason for rejecting an option was “no budget for it”, and the budget has since grown, the question can be reopened with good information.
Methods such as decision matrices and trade-off analysis can feed into a record. The matrix itself might be an attachment, while the record states the outcome and the reasoning in words. Records also complement a wider engineering design process by giving its choices a durable home, and they pair well with design reviews, where the discussion happens and the record captures what was agreed.
Avoid rewriting history. A record should reflect what was known at the time, even if it later turns out to be mistaken. A candid note that “we did not know X when we decided this” is more helpful than a tidy account written afterwards.
Where records live and how they change
Records are most useful when they are easy to find and stay close to the work. Many teams keep them as small text files in the same repository as the project, numbered in order, so they travel with the code and have a visible history under version control. Others use a wiki page per decision. Either is workable if the location is agreed and the list is easy to browse.
Records are generally not edited to change the decision. When the decision changes, write a new record that refers to the old one, and mark the old one as replaced. The trail of old and new records then tells the story of the design, including the reasons it moved on.
Where a decision involves safety, regulation or contractual obligations, a record does not replace the formal documents and approvals that apply. Rules vary by country and industry, and the people and standards responsible for those areas take precedence.
Making the habit stick
Keep the barrier low. A short template, a few minutes of writing at the time the decision is made, and a rule of thumb for when to write one are usually enough. Writing the record soon after the discussion, while the details are fresh, is far easier than reconstructing it months later. Have another participant read it, since a second person often spots a missing assumption.
Over time a collection of records becomes a quiet but useful archive. New team members can read it to understand how the design reached its present shape, and the team can see which assumptions have since changed.