- What is an ADR?
- Why use ADRs?
- Differences Between ADRs and RFCs
- How to write an ADR?
An architecture decision record (ADR) is a document intended to describe the why, what, and how of an impactful decision. Specifically, ADRs usually outline:
- Context: The circumstances and conditions that led to the decision.
- Decision: The actual choice made.
- Consequences: The implications of the decision, both positive and negative.
ADRs not only help future developers understand the rationale behind the decision, but also help align the team on important architectural choices. That being said, they are not without downsides. Some tradeoffs of ADRs:
- Improved Communication: ADRs provide a clear and structuredway to document decisions, ensuring that all team members have access to the same information.
- Historical Record: ADRs create a historical record of architectural decisions, making it easier to understand why certain choices were made.
- Onboarding: New team members can quickly get up to speed by reviewing ADRs, reducing the learning curve.
- Consistency: ADRs ensure that decisions are documented in a consistent manner, reducing ambiguity and potential conflicts.
- Overhead: Writing ADRs can be time-consuming, especially for small decisions.
While ADRs and RFCs share some similarities, they serve different purposes:
- ADRs: Focus on documenting architectural decisions and their rationale.
- RFCs: Are also proposals, but typically are used for feedback gathering, where documentation is a secondary concern.
Demo time! For latest up to date instructions, see our documentation in github. Let's look at that as well as an example: