I firmly believe there is no such thing as a "bad" or a "good" architecture. It either fits the business needs from a technical perspective, or it doesn't. A technical design is always the result of a series of "choices" and "decisions" throughout the lifetime of that design. But it's not good or bad, it's a matter of how fit the design is, given the current and historical constraints and requirements.
It's critical that you hold a good "record" or "log" of those design decisions. Because that's the reason why any design is at a certain state, at any given point in time. This post is meant to aid developers and architects into creating such "decision logs". And for this, we will use Architectural Decision Records (or ADR's).
The art of decision making
Having to make decisions on a regular basis can create a great deal of uncertainty and anxiety. Especially if that decision has an impact on the evolvability of your design. Did I think this decision over long enough? Did I take enough data into consideration? But in the end, you'll find that you never could take enough data into consideration. The data for any given situation is infinite.
And as such, worriers are people who think of all the variables beyond their control, and what might happen, and as a result are afraid to make the wrong decision.
To be clear, I'm not implying that you shouldn't think about your decisions. But you should never be afraid to make one. Even if every decision you make throughout the path of your evolving design is wrong, as long as your design is evolving, you're on the correct path. And as long as you record your decision process, you open new doors down the road, to correct the incorrect.
ADR's
Your technical documentation should have different "types". A high level (system-) design, an application design, infrastructure details, etc.
ADR's are a bit a-typical, but they should not (!) be regarded as a replacement for other types of technical documentation!
The Architectural Decision Record (as the name implies) is a log of decisions made by a team while they evolve the design of their application. It can be documented in many ways, with all sorts of templates. It should, however, always include the following information:
- ADR Lead The person(s) taking charge of the ADR.
- Status The status of the ADR in its lifecycle. Examples could be "Draft", "In Review", "Decision Presented", "Implementation started", "Implemented", "Closed".
- Context The context of the problem for which the ADR will provide a solution. What are you trying to decide? What problem are you trying to solve?
- Solution(s) Once you've defined the problem you should think about different solutions. Always try to define more than one! This motivates out-of-the-box thinking, weighing up benefits versus drawbacks, implementation costs, etc.
- Risk analysis Some sort of risk calculation. What degree of risk does the current problem introduce. How will the different solutions work towards mitigation of those risks?
- Requirements What requirements must be met? You can use the MoSCoW method, or any other system you like. Make sure your requirements are crystal clear!
- Estimations How much will each solution cost? This will impact the final decision, so this is an important part of the ADR. The most elegant solution will not always be the right solution. It should be realistic, and for this, cost/benefit evaluation is critical.
- The decision! Eventually, you'll have to make a decision. Which in turn will be presented to project management. You should be able to explain what you want to do, why you need to do it and how much time you will need. Notice that all previous steps are formal checkpoints to allow you to make the best possible choice and to take into account as much data as possible.
So an ADR, once integrated in your technical workflow, allows you to document informed decisions in a formal way. A design record is created for future reference, and can be used to present your decisions to management in a formal and conclusive way.
A solution summary will look something like the picture below.
Decision process
So, I've explained the what, who and why of ADR's. Let's take a look at the how. When documenting ADR's, keep the following in mind:
- The main goal is to document the decision process.
- An ADR should always have one person in the "lead", someone who is responsible for researching the problem. Choosing a r_ecommended solution is a team responsibility_. Giving a green light for that solution is a management responsibility.
- The whole team should be involved in the finalization of the ADR. Everyone should understand the research and the decision process. The conclusion should be unanimous. An ADR is a living document! Everyone has a say, everyone can view, and everyone has a vote. The more people involved, the better the decision will be.
- Allow all members of your team to take lead on ADR's. This allows them to become more experienced, to learn to think outside the box and gain more confidence in the decision making process.
Conclusion
Architectural Decision Records are a powerful tool for documenting the design decision making process.
Does that mean that you will now automatically make all the right decisions with these ADR's? Nope. But it will provide insights as to why certain choices were made. If the decision turns out wrong, the most valuable part is getting a grasp on why it was wrong. Who made the call, did he/she have the right information, did anyone else see the problem in a different way? This information is extremely valuable for evolving your design in the way you want, and to gain more experience in the process.
Big thanks to Karin Wauters and Marijke Walgraeve for reviewing this post.
Top comments (2)
In your example list of Status, what is the difference between "Implemented" and "Closed"?
ADRs sound interesting. I assume you're using them in your day job or main project. Was it tough to get buy-in on this additional layer of documentation? I find it hard enough to get a team to make one high level architecture diagram/document, having one for each decision sounds like a tough sell.
Any anecdotes about having this history of ADRs once a project has been going for a while? I assume it's good for onboarding new hires or collaborating with other teams. Has that worked out in practice for you? I fear that the extra work to have this history will end up like a lot of Wiki pages at companies, write-once read-never.
Hi Nick,
No real difference, were just some sample statuses. At my current team the difference between "implemented" and "closed" is just me (in my role as Architect) checking of the successful implementation of the ADR.
I feel what you say about documenting technical stuff (in the broad sense). I just starting on a very long running project and the technical documentation was either outdated, wrong or non-existent. So I just started at the beginning, documenting what I could.
But I did start with the ADRs immediately. For all of the reasons outlined in the post, but also to introduce a higher level of (technical) documentation in the team culture. And even tough it took me a couple of months, ADRs are now one of the first things we do when we change significant parts of the architecture.
Do is nothing else, it's a good place to start :).
And it's good for new hires, and for collaboration. But also to understand certain paths the team took with implementing new stuff. There no wrong or good paths; but it is worthwhile to see WHY a certain path was taken. For me as an architect, but other architects, PMO, devs, etc ;)