Writing Architecture Decision Records

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?

Sharing context

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! 🚀

Alignment

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.

Writing ADRs

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: docs/adrs/.

Use a naming convention

When saving the files use a naming convention title-of-the-adr-DD-MM-YYYY.md

Conclusion

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 ❤️