By Julius Peinelt
In any software project you have architectural decisions that need to be made along the way. When you’re working agile, this is part of the methodology. But even for waterfall projects not every aspect can be defined in advance. It has become good practice to document these decisions as so-called Architectural Decision Records (ADR).
Similar to other documentation in a project, being able to look up Architectural Decisions helps to answer repeating questions and explain the current state of the project. Depending on the quality of the record, it may even support making informed decisions on where to pivot or revise former software design choices. Imagine a project that stretches over several months or even years. The team will need to make decisions like what database to use, what frameworks to build on and how to abstract models. There are many technical aspects that are not part of the specification but still need to be decided. As the project evolves and team members change, however, these decisions will be questioned. With no documentation for the rationale behind the design choice, the team either blindly accepts a status quo that should be changed or starts refactoring things that had been done a certain way for good reason.
There are many proposals on how to document decisions. Michael Nygard suggests having fields for title, status, context, decision, and consequences for every decision. Others recommend including a field for considered options to better understand a chosen option in hindsight. Another noteworthy way to document decisions are Y-statements as proposed in Sustainable Architecture Decisions which follow the format of:
In the context of <use case/user story u>, facing <concern c> we decided for <option o> to achieve <quality q>, accepting <downside d>
In our experience, though, we found it most important to just document important decisions in projects at all — no matter the format. The goal should be to make the decision log easily accessible to all team members. Don’t overwhelm them with specs and formalism but choose a very lean and approachable style. We recommend limiting the template to the most basic and simple format possible, reducing the fields to fill per decision to a minimum. We think only three fields are necessary:
You additionally might want to record a tiny bit of metadata:
Typically, the ADRs are then stored as plain text (markdown) files in the source code repository, which is obviously not easily accessible to design or business people. Or they are recorded in a spreadsheet (Excel) document stored with the project documentation.
No matter if your team prefers plain text or spreadsheets, we have prepared two templates for simple Architectural Decision Records:
We think starting with very simple plain text or Excel template is a good way to introduce the idea of ADR to your team. In the end, it is not important if you use Nygard, MADR, Y-Statements or our style. The hard thing is to get the team on board and make it as approachable as possible for everybody to record and look up decisions. Because — honestly — documentation is boring and nobody likes to do it. So the threshold must be as low as possible.
If you and your team prefer a dedicated tool made for decision logging, you came to the right place. With Loqbooq we developed a straightforward solution that makes recording and searching decisions much more convenient and accessible. It is designed to reduce friction and helps with involving everyone from development, design and management. Loqbooq also brings additional functionality like tagging, PDF export and automatic reminders. And if your team uses Slack, Loqbooq’s Slack app lets you record, review and search decisions right from your project’s Slack channel. Start your free trial now.
Central references: