Origin of the Architecture Decision RecordsADRs originate from the practice of evolutionary architecture. This architecture discipline thinks about the changeability of software. From this comes the realization that software evolves incrementally through adaptations and extensions. Also, decisions are time-dependent. This type of documentation can be traced back to an idea by Michael Nygard in 2011. His employer at the time, ThoughtWorks, placed the idea at several events. Today, ADRs are part of the mainstream.
Knowing and not knowingArchitectural decisions have many influencing factors. Also, our knowledge is a conscious influencing factor. We know what we know. And we also know what we don’t know. That sounds plausible. But our lack of knowledge also influences decisions. We make some decisions based on our instinct without being able to give reasons for them. The lucky mushroom intuitively makes the right decision. But how do we know if we belong to the lucky mushrooms?
Learning from each otherCommunication is an essential means of learning knowledge. By talking to each other, we exchange our knowledge. That which we know, we can pass on. And what we don’t know, we can ask. But in the group, we can also uncover our blind spots. What is intuitively correct can be backed up with facts by my counterpart. Or my wrong knowledge can be refuted with arguments. In this way is how we all learn from each other.
Learning with the Architecture Decision RecordsThe ADR takes up the previously mentioned aspects and consists of several sections:
- The title describes what the issue is.
- The context describes the conditions that led to the decision.
- The decision itself was made based on the information in the context.
- The status in the life cycle of the decision: Proposed, Accepted, Discarded, Deprecated, or Superseded.
- The consequences of the decision, as advantages and disadvantages.
ADR ToolingDocument decisions in simple text form. Tools are not necessary. However, tools can be helpful in processing ADRs. Nat Pryce has published a collection of ADR tools.
Documentation is only good if it provides the proper knowledge. Documentation is not an end in itself. ADRs thrive on team spirit and are helpful if the team supports them. If not all involved are willing, this can also be a reason against documentation. This reason often applies when the team is afraid of making difficult or unpleasant decisions.
Does this article meet your interest? Then take a look here as well!