AOE Technology RadarAOE Technology Radar

ADRs have proven to be a useful tool for documentation and are commonly used in our organisation. We therefore promote it to the "adopt" ring.


Architecture Decision Records

ADR is a lightweight documentation of important architecture decisions taken by the team. Without documentation of the architecture and the architecture decisions, new team members can only do two things:

  • either (blindly) accept what they find and see or
  • (blindly) change things

It goes without saying that both options aren't right.

Therefore, we suggest documenting the important architecture decisions. We use a simple tool such as and store them in version control. In larger projects with many teams we also establish a regular "architecture board / COI" with regular meetings. Often, the architecture decisions are taken in such meetings.

The main purpose of this documentation is to:

  • inform new team members about the previous architecture decisions and their purpose and backgrounds
  • inform the whole team (including all people who were absent)
  • create documentation that can be used to remember things (e.g. conventions, patterns, etc.)