Deciding on ADRs
Decision
For introducing an ADR, first find a second person that champions the ADR with you. Then create a first version of the ADR based on the template.
The first version should contain only the Problems and Context sections. Do not add any ideas for solutions yet! Instead, share the problem statement as a PR via a Slack message in #product-main and start gathering feedback.
While gathering feedback, fill out the rest of the ADR document and share it again. Depending on the topic of your ADR, there should be a couple of days up to one month for the feedback phase. It might make sense to ask specific people for feedback, and to take into consideration that people might be away on vacation.
Once you are ready for decision, bring the ADR to the next cross-team retrospective to decide on it. If there is no unanimous decision in that cross-team retrospective, use the time to the next cross-team retrospective to try to understand the resistance.
An ADR will be approved if everybody is on board at the end of the discussion in the cross-team retro.
If someone says that the decision will block them over the next 2 weeks, the CTO can make a decision in an earlier cross-team retro.
Problems
Only few people initiate ADRs or participate in ADR discussions. When talking about this in a cross-team retrospective, the following reasons surfaced:
- It was not always clear how an ADR would affect a specific team, so that team put a low priority on understanding and discussing that ADR
- Not all suggestions on ADRs were adopted before merging an ADR and the process for deciding on ADRs was unclear
- Writing an ADR seemed daunting and time-consuming
- It was unclear which kind of decisions would need an ADR and which wouldn't
Context
Currently, the way we write the ADRs is quite brief. The current format does not include ownership or rollback processes. There is no predefined timeline for going forward.
Options
ADR Format
- We use very short ADRs with the minimum information needed
- We use very extensive ADRs with deep upfront research on implementation details
Decision process
- ADRs are decided upon by the CTO
- ADRs are voted upon by all developers
- ADRs are discussed until consensus
Reasoning
ADR format
The format needs to balance being too short, which would lead to making decisions with missing or wrong information, with being too long, which would deter people from even starting an ADR and thereby would lead to undocumented ad-hoc decisions.
The template tries to cover all important areas while still making it easy to start with only two sections, and not having too much work needed to complete an ADR.
Decision process
Top-down decisions might lead to bad decisions due to missing knowledge about the day-to-day context. It could also be demotivating for those who are affected by a decision without being able to influence it.
Voting could discourage discussion, as it might be easier to vote against an ADR, than to find constructive alternatives.
Enforcing consensus puts the burden on each participant in the discussion to prioritize which fights are worth fighting, and to think about alternatives.
As a fallback, the CTO can decide in case there is no consensus. This hopefully encourages finding consensus, and should not ever be actually needed.
Consequences
How do we implement this change?
All templates and technical changes needed are included in the PR for this ADR. The cross-team retrospective, which is the decision meeting mentioned in the PR, already exists.
Who will implement the change?
The change is already implemented by the time this ADR is merged.
How do we teach this change?
We already have the first few ADRs being created out of the teams. The CTO will actively encourage teams to add ADRs wherever a related topic comes up in a review and support on writing them with feedback.
What could go wrong?
- The structure might be too complicated and people are still discouraged from starting their own ADRs
- The ADRs might not contain enough information, and decisions might have to be rolled back due to erroneous decisions
- ADRs might not get implemented
What do we do if something goes wrong?
The template and the process can easily be adjusted with further ADRs.
What is still unclear?
It isn't 100% clear yet whether the new process will really encourage more participation and initiative around ADRs, or whether there are some deeper problems that we missed.