funkyfrogstock - Fotolia
4 best practices for creating architecture decision records
An ADR is only as good as the record quality. Follow these best practices to establish a dependable ADR creation and maintenance process.
In a software project, enterprise architects need to make numerous decisions concerning the structure of the architecture, the frameworks their teams will use, and other key considerations that impact development processes. Development teams need to be kept in the loop about what those decisions are and when they will take effect. And, more importantly, those teams need to know why those decisions are made.
This is where an architecture decision record (ADR) comes in. This is a document that records the reasons for making any big decision related to the architecture of an application. With it, developers and architects can review why and in what context a certain change was made, which helps them understand which direction the architecture is headed in overall. For example, recording every change made during the process of completely revamping the architecture is an extremely important part of keeping that project on track.
In this article, we review some architecture decision record best practices for enterprise architects and development teams to follow.
1. Identify the problem and add context
An architecture decision record entry starts with a requirement or a problem. This problem is discussed with the team, and all possible solutions are considered. Providing context of the problem in the record is critical. For instance, identify the background problem that sparked a decision, the flow of dialog between the team members, opinions that influenced the final course of action, and the ultimate consequences of that action.
2. Focus on one single decision
Recording multiple decisions into a single architecture decision record will confuse readers, especially when it is reread later in a completely different context. Try to ensure that a single record focuses on one specific set of related decisions. Don't make your entries too high-level or in the weeds. Remember, it should contain just enough detail that readers can understand the high-level objectives and history. Don't clutter the record with day-to-day decisions; focus on documenting the big ones. For example, a typical engineering team's ADR will likely have about 30 to 50 entries per year.
3. Use a template
An architecture decision record template helps establish consistency and improve the quality of entries. A simple template is all you need to start, and there are plenty of customized options to implement later if need be. There isn't one right way to approach this, so do what works best for you. Explore the resources available to quicken the learning process around architecture decision records. GitHub is home to many of these options, such as a LADR template (the L here stands for lightweight). Some of these templates rely on simple Planguage (plain language), while others contain a much more detailed account of the decisions made (shown in the following image).
4. Train your team members
Every team member should have the opportunity to master the art of writing an architecture decision record. This fosters design thinking across the team, and improves the quality of discussions surrounding architectural decisions. However, keep in mind that an official ADR should never be altered or revised after the fact. It must remain an immutable and reliable source of truth. As such, architects or senior developers should review decision records written by lower-level staff before they are actually placed in the ADR.
