Architecture decisions deserve preservation equal to the code implementing them, because those decisions are also at risk for being lost. While architectures are usually well documented, the options and choices made during system planning are often lost after a diagram is published. This is certainly the case when the planners move on without documenting their thought process. This history is incredibly important for future maintainers of a system. For this reason, it makes sense to use the same audit mechanism for architecture and code. Architecture decisions should be recorded in source control, just like comments in code.

What is an ADR?

ADRs are evidence of due diligence in the selection process.

Architecture Decision Records (ADR) are a best practice for documenting why an architecture is chosen. Every cloud provider offers a rapidly evolving product. The architectural choices made today are based on the features available today. Features could be different tomorrow, so the available solutions and decision process should be documented. This allows later contributors to understand why systems are architected a certain way. ADRs are evidence of due diligence in the selection process. Architects, business partners and development teams benefit from their existence!

How is an ADR composed?

The next few articles will focus on the substance of ADRs for cloud systems. We’ll also consider tooling to make the process easier. Let’s begin!

• Framing ADR Context
• Referencing ADR Entries (Coming Soon)
• Formatting ADR Entries (Coming Soon)
• Finding ADR Candidates

Additional Resources

Learn more about ADRs at:

• https://adr.github.io/
• https://cloud.google.com/architecture/architecture-decision-records
• https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records