Architecture Design Records (ADRs) are a method of documenting crucial architectural decisions made during a software project. The term “Architecture Decision Records” was first introduced by Michael Nygard in a 2011 blog post. ADRs serve as a record, explaining why certain decisions were made, encapsulating the context in which they occurred, the pros and cons evaluated, and the impact of each decision.
ADRs are especially valuable as they provide historical context for the choices made by the development team. This context can guide future developers in understanding why a system was designed a certain way, and assist them as they continue to evolve the system.
ADR Format
Each ADR is a simple text file, typically written in Markdown to ensure consistent formatting and structure. It generally comprises:
- Title: A succinct, descriptive name for the architectural decision.
- Context: An explanation of the forces at play, including technological, political, social, and project-specific aspects that led to this proposal.
- Decision: The actual proposed change, stated in full sentences.
- Status: A brief statement of the current status of the decision, such as “proposed,” “accepted,” “rejected,” or “deprecated.”
- Consequences: What will be the outcome? All potential effects, not just the “positive” ones, should be included here.
These records are generally placed in a well-known location within the project’s version control repository. Developers are encouraged to review and contribute to them as part of their development process. As an integral part of a system’s “documented history,” they should be written and maintained with utmost clarity and precision.
While some of the most well-known tooling for managing ADR are primarily aimed at Node.js or JavaScript developers, as a .NET developer, you might find these tools less intuitive or harder to integrate with your workflow. That’s why I recommend checking out dotnet-adr, a CLI tool specifically designed to make working with ADRs easier in the .NET environment.
Getting Started with ADR in .NET
The dotnet-adr website offers a lot of interesting information about ADR in general and a very clear getting started section. For brevity I will include here a brief list of steps to start working with ADR in your project.
1 – Install dotnet-adr, opening a terminal window and using the following command
dotnet tool install -g adr2 – Initialize a folder in your project as the repository for your ADR. Go the the root folder of your project and use the following command
adr environment initThis command will create a docs/adr folder on your project.
3 – Add your ADR, usually your decision to start using ADR. Go to your adr folder and use the following commands
adr new "Use Architectural Decision Record"
adr new "Use Xamarin.Forms"Now you will have two new markdown files (0001-use-architectural-decision-record.md and 0002-use-xamarin.forms.md) to edit with your preferred editor to fill the blanks on the template.
4 – If any of your existing ADR will be changed for a new one, you can supersede it with the command
adr new "Use MAUI" -i 2This will create the record number 3, but keep in mind that you will need to manually modify the document for number 2 to include the superseded status.
5 – Check the templates related documentation to find and use the format that best serve to your project.
Conclusion
Architecture Design Records (ADRs) are an indispensable tool for maintaining transparent and comprehensive documentation of key architectural decisions throughout the lifecycle of a software project. They not only provide essential historical context but also guide future developments. As a .NET developer, getting started with ADRs may seem intimidating initially, but with the right tooling and methodology, it becomes a seamless part of your development workflow.
It’s a practice worth investing in, as it pays off tremendously in the long run by ensuring a clear understanding and rationale behind each significant decision, promoting effective and coherent team communication.
