AOE Technology RadarAOE Technology Radar
This item was not updated in last three versions of the Radar. Should it have appeared in one of the more recent editions, there is a good chance it remains pertinent. However, if the item dates back further, its relevance may have diminished and our current evaluation could vary. Regrettably, our capacity to consistently revisit items from past Radar editions is limited.
Adopt

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.

Assess

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 https://github.com/npryce/adr-tools 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.)