The Architecture Decision Record (ADR) is a tool that helps you write documentation that others will actually read. Nobody wants to read a 100-page document to understand the architecture of a system they are working on, so ADRs are short documents written in a simple formatting language like Markdown. They have three main sections: a context, a decision, and a status.
In the context section, you describe the problem you are trying to solve and the forces at play (such as politics, product strategy, leadership direction, technical debt, and so on). You need to be transparent and explicit about the context.
The decision section describes how you will solve the problem. This can include text, diagrams, API references, or whatever is needed to explain your solution.
The status section reflects the outcome of discussing the document with stakeholders. It can be “proposed,” “accepted,” “rejected,” or later on, “deprecated.”
After you have implemented the decision, you can come back to the ADR to describe the consequences and outcomes of the implementation.
It is important not to be dogmatic about using ADRs. They are a tool, and like any other tool, they require discipline and alignment to get the most value out of them.
▬▬▬▬▬▬ Support the channel 💜 ▬▬▬▬▬▬
Every little bit helps ✨
- Join the journey on Patreon: https://www.patreon.com/glich_stream
- 1 time support: https://www.buymeacoffee.com/glich.stream