When should you write an architecture decision record (ADR)?

Question

Documenting your software architecture through Architecture Decision Records (ADR) seems to be regarded as a best practice in software development.

Influential content on the topic includes the folling:

• https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
• https://adr.github.io/

The why and how are pretty clear to me. My question is "When should you write an ADR?" Or in slightly different words, "What should you capture in an ADR?"

Answer 1

Well, there are different opinions how ADR process should look like.
I have found the following the most useful one:

• Create a new record whenever you need to introduce a technology or procedure
  • and you have done your assessment
• Revise them regularly (quarterly is most probably enough)
• Use it to reason about your system

ADR is all about to make concise decision by capturing why did you choose X and why did you exclude Y and Z. These decisions can't be read from your code, so that's why it is essential to document them.

And don't forget that they are living documents. It is in iterative process to make them up-to-date and valuable.