iSAQB Software Architecture Gathering
In connection with her SAG 2026 session “Decisions for Software Design and Beyond”, Jacqui Read answers questions by Richard Wallintin (WPS – Workplace Solutions) about the importance of Architecture Decision Records (ADRs), how to document architectural decisions effectively, and why understanding trade-offs and the reasoning behind decisions is essential for sustainable software architecture.
1. Should basically all decisions (architecture, design) be recorded in detail? What's the threshold for relevance (any heuristics)?
Recording every decision would be a full-time job. What we need is a useful record.
There are two big considerations: what decisions we should make and what decisions we should record.
We should only make decisions for which we have the necessary knowledge, experience, and stake. An architect should not make all the decisions about software implementation. Those decisions are either for the dev team to make, or for the architect and dev team to make together.
When it comes to which decisions we should record (here is a sneak peek from my talk) record the decision when:
– it keeps being questioned: pointing people at the record will save time explaining the decision or working out why it was decided that way over and over again.
– it is complex or hard to understand: you don’t want to go through that decision making process again when things change, or explain a complex decision.
– it affects how developers will write the software: you aren’t going to make all the decisions for developers, but your decisions often affect how developers will make their own decisions. You want them to be able to understand your decision so they can make their own informed decisions.
2. What is the right level of detail and how much rationale needs to be explained? In the end, walls of text will not be read…
Never give people walls of text to read. You do not need to record every detail, and you have many tools such as headings, bullets, bold, etc. to help people easily understand and scan your decision.
A lightweight decision record is the most common type. These are used to simply record the decision. I would include the status (draft/decided/superseded), the context around the decision, the decision made, the options considered, and the implications of the decision (there is always at least one trade-off).
If you want the decision record to help you make the decision, you can create an enabling decision record. These include the same information as a lightweight record, but also contain the evaluation criteria you used (e.g., requirements, constraints), and a consultation section for gathering input.
3. Often decisions are made somewhat incidentally and recorded retrospectively. (Which is certainly better than not recording them at all.) Should decisions be revisited in these cases to encourage deliberate decision making?
No one ever regrets recording a decision.
When recording a past decision I call it a historical decision. Create the decision record when you discover the decision and record all the information you have. If you don’t know something state that you don’t know, and where you have looked for the information. Someone might be able to fill in that information at a later date.
You may benefit from having the decision recorded in the future, but you also benefit from reviewing the decision as you record it. You might notice that something has changed or that something was missed. Maybe this decision was made before a particular technology came about, or before a law came into effect. Maybe an important criterion was forgotten. You can then decide if the decision needs a proper review and create a new decision record that supersedes the historic one (and might change the decision or decide not to change it).
4. What element of ADRs is the most-overlooked in your opinion? (There are lots of ADR "templates", what should not be missing?)
Always record the implications of the decision, positive and negative. There are always trade-offs when we make decisions and those should never be ignored. If you can mitigate any negative implications, record those mitigations. Recording mitigations gives them a chance of being implemented, but they are also part of your decision-making process. Yes there are negatives, but we can mitigate the negatives of this decision, making it the better option…
Recording the criteria used to make a decision is incredibly useful if that decision is revisited. When those criteria are viewed it is easy to see if something important has changed. Maybe this decision was forced due to a restriction that no longer exists. The criteria that were used are also often the best way to answer a question about the decision. Why did we choose technology X over technology Y? Y did not meet our criteria for data residency. Question answered in record time (pun intended).
5. Do you think a decision trail alone can be sufficient architecture documentation? What's the relationship of ADRs to component models, deployment views, etc.?
A decision trail ties together and explains your documentation. Documentation does not need to be extensive, but it does need to explain itself.
Decision records should link to related requirements, assumptions, constraints, and other documentation. And the documentation should link to the decision records. Here is the design and architecture, and here is a link to why it is designed this way. Here is the decision, and here are the criteria used to make that decision and the designs that implement this decision. Both the how and the why must be present. (See ACEDmodel.com for more on how and why)
You need to load content from reCAPTCHA to submit the form. Please note that doing so will share data with third-party providers.
More InformationYou need to load content from Turnstile to submit the form. Please note that doing so will share data with third-party providers.
More InformationYou need to load content from reCAPTCHA to submit the form. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from Turnstile. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from Vimeo. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from YouTube. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More InformationYou need to load content from reCAPTCHA to submit the form. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from Facebook. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from Instagram. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from Google Maps. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More InformationYou are currently viewing a placeholder content from X. To access the actual content, click the button below. Please note that doing so will share data with third-party providers.
More Information