[timwis]

I’m hoping to implement this in my organisation very soon. There are still a couple things I need to figure out:

1. How do I articulate the criteria for when a decision should have an ADR?

2. I always see ADRs in the context of recording what was decided, but I’d like them to be raised more like requests for comments (RFCs) for a week or two first, particularly in cases where there may be impacts on other systems, security or data protection implications. Are ADRs often used this way, or should I be looking at something else?

Any advice?

[willejs]

1. I usually advise people to raise an ADR when they are adding new component to a system, a new technology, or really anything that they feel needs context and want to have a discussion about. Usually I advise either making a pr in the repo for that component (this can be in #1 with the first commits of code) or in a centralised docs repo when you are adding new technologies to your stack or setting standards etc. 2. I have used them in place of RFCs at a couple of places. Generally I would write code or docs alongside an ADR and use the comments in a pull request to get a review on it, and try to improve the PR with the comments. If there is a consensus in the PR from enough people it would get merged in, if not i would take it to an appropriate forum to discuss it (guild, standup, meeting etc).

I have found creating a couple of ADRs in a team and getting that team to participate in the process first is a great example to showcase to an organisation at a show and tell, lunch and learn etc. Adr-tools is a great tool to help create an ADR and provides a good template too!