Architectural decision records (ADRs)
Your architecture will change with time and in the future you may have to investigate why your architecture is a certain way. Architectural decision records (ADRs) help by providing an archaeology of your project.
To learn how to write ADRs, start with Joel Henderson’s guide to ADRs. You’ll find many templates to get started with. Here are some good practices.
Like meeting notes, ADRs should live in a central location for the project. You can use collaborative file sharing tools like Google Drive or wikis like Confluence. A sensible default, however, is to store them in source control, with your code.
No decision is too small to document. In fact, the cost of your undocumented change is just as high as that of the first duplicated effort in your team or organisation. ADRs are lightweight, so take a few minutes to write the change down.
If you come across an undocumented decision, be a good citizen. Collaborate with your team to document it, so you avoid confusion in the future.
Last but not the least, write ADRs in a way that everyone on the team can understand. You know your ADR is impactful when both techies and business folks can understand the rationale behind your decisions and the solutions you’ve arrived at.
ADR-manager (below) is a tool that integrates with your GitHub repository. It allows you to browse and edit past ADRs. If you want to create a new ADR, then it guides you through the process by providing a consistent format.
ADR manager in action