Architecture Decision Records

One of the most popular tools for documenting architectural decisions is an Architectural Decision Record (ADR). An ADR is a document that describes a choice made by the team regarding a significant aspect of the software architecture they’re planning to build. "Significant" means that the decision has a measurable impact on the architecture and quality of a software or hardware system.

The collection of ADRs created and maintained for a project is referred to as the project decision log.

A basic ADR typically includes the following parts:
- Title: The name of the change.
- Status: The current status from the ADR lifecycle, such as draft, accepted, rejected, deprecated, etc.
- Context: The purpose of the ADR, the issue it aims to solve, business priorities, team skills, and limitations.
- Decision: A description of the proposed change.
- Consequences: The effects of the change, including what becomes easier or more difficult, as well as any outputs and after-review actions

It is a good practice to review ADR after implementation to compare the documented information with what was actually implemented.

Company-specific ADR process examples:
- Github ADR
- AWS ADR Process
- Google Cloud ADR Recommendations

ADR is a good tool to document architectural decisions, improve internal communications and facilitate knowledge sharing within the team or across the organization.

#architecture #documentation