"Documenting architectural decisions helps a project succeed by helping current and future contributors understand the reasons for doing things a certain way." [1]
An architecture decision record is a short text file in a Markdown format. Each record describes a set of forces and a single decision in response to those forces. [2]
An ADR is not a technical design, a team-level internal procedure, or a roadmap. An ADR does not replace detailed technical design documents or good commit messages.
We will keep each ADR in a short text file in Markdown format.
We will keep ADRs in this repository, https://github.com/opendatahub-io/architecture-decision-records .
ADRs will be numbered sequentially and monotonically. Numbers will not be reused.
If a decision is reversed, we will keep the old one around, but mark it as superseded. (It's still relevant to know that it was the decision, but is no longer the decision.)
We will use a format with just a few parts, so each document is easy to digest.
- https://www.redhat.com/architect/architecture-decision-records
- https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- https://github.com/operate-first/blueprint/tree/main/adr
- https://adr.github.io/
- https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html
- [1] Heiko W. Rupp, https://www.redhat.com/architect/architecture-decision-records
- [2] Michael Nygard, https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions