An architecture decision record also known as ADR, is a document that captures an important architecture decision, including the context of how the decision was made and the consequences of that change.
What are the benefits?
ADRs capture a decision at the time it's being made. They're the outcome of all of those asynchronous discussions in Slack that'll be lost over time ⏰
When you materialize them into docs, you're allowing your future teammates, to get the context for this specific change. So they'll be able to understand the issues, the decision that was taken and the impact it had on the project.
Writing docs will help you and your future peers in the long run! 🚀
Writing decisions leads the team to consensus and ensures that all the assumptions of a change are clear 📏.
This will have a positive impact after the architecture decision has been implemented. Everyone on the team will have a deep understanding which will help on moving forward faster with the new approach.
Define a template
When writing them, a common practice is to have a template to write ✍🏼 all the documents in the same way.
You'll find a lot of templates online, but here's the one I use it's very simple but easy to write.
# Title - Status: <!-- PENDING/APPROVED/DEPRECATED --> - Date: DD/MM/YYYY - RFC: <!-- Link to the RFC that ended up into the ADR --> ## Context <!-- What is the issue that is motivating the decision or change? --> ## Decision <!-- What is the change we're doing? --> ## Consequences <!-- What becomes easier or more difficult because of this change? -->
Store them next to the code
I believe that documentation should be next to the code to make it easy to contribute to it. Whenever you add an external tool you're increasing the complexity to contribute and reducing the visibility of the docs 👀.
The solution is simple, check out the ADRs into your project repository and keep things simple and clean ✨
I recommend you to create a folder 📁 where you store all the decision records, for example:
Use a naming convention
When saving the files use a naming convention
Write more ADRs 😜, if you're not doing it yet, it's never too late to start!
In my experience as a team grows larger and a codebase becomes more complex, architecture decision records are a great tool to help your current and future team ❤️
Top comments (2)
Hi Carlos, great post 👍. Do you know any public repos with examples of this? Actual real ADRs?
Hey! Thanks for the comment 😊
Here's a repo that includes some examples github.com/joelparkerhenderson/arc...