Creating Architecture Decision Records

March 28, 2024#Software Development
Author image.

Sarah Dutkiewicz, Senior Trainer

We can’t stress the importance of documentation in software architecture. The decisions that you make today will impact the project now and may lose context and understanding in the future. Documentation can help others understand what problem was being addressed, what options were considered, and why a decision was made.

As I mentioned in the Practicing Architecture Katas post, Nate Schutta mentioned architecture decision records (ADRs) during his “Thinking Architecturally” workshop at CodeMash. When I attended Explore DDD earlier this month, I heard about ADRs in many sessions. In one, Indu Alagarsamy suggested that decision records could apply to architectural decisions, product design decisions, or other decisions involved in a business. I’m a huge fan of documentation, so if I can document it, I will.

Screenshot of Indu's template for a decision record - including title, what to decide on, the context, recommended decision, supporting arguments, consequences/constraints, other options considered, impacted stakeholders, and related references.

What to Include

What are some of the things to include in a decision record? Some of the things you might want to capture include:

  • Title
  • Status: such as Draft, Proposed, Accepted, Rejected, Deprecated, or Superseded
  • Problem
  • Options
  • Decision
  • Consequences / Outcomes

Depending on the company environment and the person documenting the decisions, there may be other things included, such as:

  • People and/or departments involved in making the decision
  • Cost matrixes and comparisons for multiple options
  • Analysis artifacts
  • References to related decision records
  • References to resources involved in any research to assist in decision making

When to Write Decision Records

In the CodeMash workshop, one of the attendees asked about when ADRs should be written. If you can capture everything in context, that’s the best.

Can we write decision records retroactively?

Yes, and by doing so, you capture as much as you know about the decision that was made, making note that the decision record was created retroactively and that certain contexts may not be caught. If you’re capturing a decision record retroactively, be explicit about what details or contexts are missing.

Where to Store Decision Records

Another question that came up during the workshop is where to store ADRs. Typically, you want them to live in a spot where they can be seen by everyone they impact. This could be something like a document within a document controlled environment, a folder on an intranet, or some other document storage system. It also helps to link related ADRs by referencing IDs or using hyperlinks where possible.

With the developer mindset, there’s a question of Can my decision records live in the same repo as my code? I’m going to caution you on this - will those impacted by these decisions be people outside of the source control? Would the documents living in a repo make it complicated for stakeholders to access it? Do you have non-technical stakeholders who wouldn’t need repo access otherwise? While I understand why you would want to include decision records with your code, I would caution against it unless your decisions that are in your repo are purely related to the code stored in the repo and impact only those who need to access the repo.

Sample ADR

One of the things we do at NimblePros is have lunch-n-learns around architectural topics. In a recent lunch-n-learn, we were proposed the following situation:

We have a shopping website. How can we get info on the book price from within the shipping module?

As we were talking about possible solutions, I thought - I should create a sample ADR! So I did, and you can get it here: Sample decision record.


By documenting what decisions were made, why they were made, and the context surrounding them, teams can navigate complex architectural landscapes with confidence and coherence. Storing ADRs in a centralized storage location accessible to all stakeholders ensures visibility and fosters collaboration, while establishing a culture of continuous improvement and learning. Whether it’s outlining architectural principles, documenting trade-offs, or capturing rationale behind design choices, ADRs serve as a compass guiding teams towards architectural excellence.

Embracing the practice of writing and maintaining ADRs not only enhances the quality of software systems but also cultivates a shared understanding and alignment within the team. As the software industry continues to evolve, the adoption of ADRs stands as a testament to the commitment towards building robust, scalable, and maintainable systems that meet both present and future needs. The decisions that you make today will impact the project now and may lose context and understanding in the future. Capture the current context so that future you understands why and how this decision was made. Document your decisions in decision records!

Additional Resources

Copyright © 2024 NimblePros - All Rights Reserved