ADRs

Decision

We use a custom ADR format to document all major technological decisions and show the status of architectural discussions with help of a tech radar.

Problems

Our team is growing, and multiple teams start to tackle similar technical challenges. E. g. multiple teams try to improve our CI server, but they use different approaches.

In addition, new joiners do not have a good overview which technologies we use.

This creates confusion about which technologies to use and unnecessary duplicate efforts.

Context

We already document some decisions in Confluence, including spikes for new challenges. We do not do this consistently, and we do not have documentation for many foundational decisions from the past.

Some of us have already worked with ADRs, but not all of them.

Options

• Documenting decisions in Confluence
• Leaving decisions up to individual teams
• Documenting decisions via ADRs
• Documenting technologies used via a tech radar

Reasoning

Confluence is not close enough to the code and therefore easily grows stale. It also doesn't allow an easy automated integration with a tech radar.

Leaving all decisions up to the individual teams would create a huge workload for each team, as each team would need to evaluate all options for themselves, and we would need to separate out all code more clearly to avoid decisions affecting other teams.

ADRs are a recommended industry standard and will allow us to simplify discussions and onboarding. They do not give a good overview, though, so we need to combine them with a tech radar.

Consequences

We will need to take time to set up all ADRs for foundational decisions and move them through the tech radar decision cycle.

We also need to train everyone on how to read ADRs, as well as training at least one person per team on how to write them.