Software Documentation — ADRs

How to document architectural decisions and avoid the loss of context in software systems.

Introduction

Since the beginning of my career in technology, I have relied heavily on documentation. To be honest, without it I probably wouldn’t have evolved in the same way.

Although this may sound obvious, there is an important point worth highlighting: when joining a new team, project, or company, it’s common to develop a false sense of autonomy — especially when we already have experience. This “senior ego” can lead us to move forward without fully understanding the context, the established practices, and the decisions that have already been made.

Joining a project without context is like entering a city without a map.

Developing software without understanding the asset you are working on is a recipe for failure. It can lead to frustration for professionals, who struggle to demonstrate their capabilities, and for companies, which often fail to clearly identify what is preventing greater productivity, agility, and talent retention.

And where does documentation fit into this?

Among the various types of documentation that exist, there is one in particular that addresses a recurring problem in software projects: the loss of context behind architectural decisions over time. This is where ADRs come into play.

A software system is not just running code, but the accumulated result of decisions made over time. Architectural Knowledge Management (AKM) treats these decisions as organizational knowledge rather than temporary technical choices. ADRs provide a simple and effective way to make this knowledge explicit and versionable.

Architectural Knowledge Management (AKM)

Before discussing ADRs directly, it is important to understand the concept of Architectural Knowledge Management (AKM).

AKM is the practice of capturing, organizing, and sharing a system’s architectural knowledge over time. This knowledge is not limited to diagrams or isolated technical decisions, but also includes:

• the context in which decisions were made;
• the constraints that existed at the time;
• the trade-offs that were considered;
• the alternatives that were discarded;
• and the expected consequences of each choice.

In real-world projects, much of this knowledge ends up existing only in people’s memory. As teams change, projects evolve, or companies grow, this knowledge is gradually lost. The result is common: decisions being revisited, problems being rediscovered, and previously resolved discussions resurfacing.

AKM emerges precisely to prevent this loss of context.

Within this scenario, Architecture Decision Records (ADRs) appear as one of the main mechanisms for recording and preserving architectural knowledge. They do not replace other types of documentation, but instead act as a historical record of the decisions that have shaped the system.

In other words, AKM transforms architectural decisions into persistent knowledge.

The ADR’s

ADRs capture the context and trade-offs behind architectural decisions.

ADRs were first mentioned in the article titled Documenting Architecture Decisions by Michael Nygard in 2011. The article argues that one of the biggest problems in software engineering is the loss of context, and that ADRs provide a way to capture the context, the decision, and its consequences. According to the author, traditional architecture documentation is flawed because it is static, while ADRs make it dynamic and time-aware.

In the book Fundamentals of Software Architecture (2020) by Mark Richards and Neal Ford, there is an entire chapter dedicated to ADRs. This book, in particular, is considered by many architects to be the modern bible of software architecture, reinforcing the importance of documenting architectural decisions. In the first chapter, the authors introduce what they call the “Two Laws of Software Architecture,” which are:

First Law: ”Everything in software architecture is a trade-off.”

Second Law: ”Why is more important than how.”

In Chapter 19, there is a very clear explanation of why ADRs are important, along with an additional emphasis on the idea that code documents the “what” and the “how,” but not the “why”:

“Design diagrams and source code can document how a system is built, but those artifacts don’t document why a certain decision was made. Architecture decision records (ADR’s) capture the rationale — the context and the trade-offs — that led to a particular architecture decision, providing a history for future architects and developers.”

A common question is: when should an ADR be created? In general, ADRs are recommended when a decision:

• impacts the architecture or the way the system evolves;
• has more than one viable alternative;
• involves significant trade-offs;
• may raise questions in the future.

Not every decision needs to become an ADR. The goal is not to document everything, but to preserve the context behind difficult decisions.

ADRs do not replace complete architectural documentation, diagrams, or functional documentation. Instead, they complement these artifacts by recording the why behind decisions, not just the how.

The most common ADR structure typically includes: Title, Context, Decision, Comparison with other approaches, Pros and Cons, Benefits, Next Steps, and Related items.

• Header Title Status: [Options: Proposed, Rejected, Accepted, Deprecated, Superseded (indicate by which ADR)] Decision Makers: People involved in the decision Creation Date: When it was added to the documentation Last Updated: Date of the most recent change
• Context Description of the current situation or the need that led to this decision. It is important to explore existing limitations, opportunities for improvement, or identified problems.
• Decision The final decision made after analyzing other possibilities. Highlight the main factors that led to this choice compared to the other available options. Be concise in this section.
• Comparison with Other Approaches Simply describe which other options were evaluated.
• Pros and Cons List the main benefits of the decision, including technical, business, or maintenance advantages. Also list the risks and limitations identified.
• Next Steps Actions to be taken moving forward. For example, monitoring observability metrics, or waiting for an external factor to occur before transitioning to approach Y described in ADR-123.
• Related Links to ADRs related to this one.

We can use the following ADR as an example:

# ADR-012 - Use of Entity Framework 9

## Status

Accepted

## Decision Makers

Architecture and Platform Team

## Creation Date

2026-02-01

## Context

The project currently uses .NET 9 in the development environment. However, the production environment has restrictions related to the SDK and approved libraries, being compatible only with specific versions of Entity Framework.

During dependency updates, it was identified that previous versions of Entity Framework presented incompatibilities with libraries used in the persistence layer, as well as limitations in features required by the project.

## Decision

Adopt Entity Framework 9 as the project's standard ORM, ensuring compatibility with the SDK available in the production environment and support for the functionalities required for system evolution.

## Comparison with Other Approaches

* Keep using Entity Framework 8
* Migrate to Dapper as the primary solution
* Implement a hybrid EF + Dapper approach

## Pros and Cons

### Pros

* Compatibility with the production environment
* Better integration with .NET 9
* Reduction of infrastructure code

### Cons

* Direct dependency on Microsoft's roadmap
* Possible need for adjustments in future updates

## Next Steps

* Monitor performance of critical queries
* Review the decision after production environment updates
* Evaluate hybrid usage with Dapper for complex queries

## Related

ADR-005 - Data Persistence Strategy

Some important points to consider about ADRs are that they were originally proposed to be written in Markdown format and should be part of the code versioning cycle.

In today’s era of AI, agents, and tools that automate and enhance productivity in software development, ADRs become a strong ally because they provide what is most important for an AI agent: context. If your documentation contains enough context for an agent to work effectively with its prompts, the chances of hallucination are drastically reduced, and the use of ADRs helps make this possible.

Without context, even AI makes wrong decisions.

Common Anti-Patterns When Using ADRs

Example:

• creating ADRs for trivial decisions
• modifying an existing ADR instead of creating a new one
• using ADRs as late documentation
• creating ADRs without context

Conclusion

ADRs do not exist to bureaucratize development, but to preserve knowledge that would otherwise be lost over time.

Systems evolve, people move between teams, and decisions are revisited. ADRs ensure that, even years later, it is still possible to understand not only what was done, but why it was done.

In the next articles of this series, we will explore how ADRs connect with architectural diagrams, living documentation, and modern software engineering practices.