← Back to all articles

How to Use ADRs Without Turning Them into Bureaucracy

Published

Keeping Architecture Decision Records (ADRs) is a great idea. However, strictly following all ADR guidelines can quickly turn into a bureaucratic nightmare.

As often happens with documentation, it can become a burden rather than a helpful tool. Let’s figure out how to maintain ADRs without spending excessive effort on filling them out and keeping them up to date.

Recommendations for Maintaining ADRs

  • Use a single file for all records if you have a small or new project with fewer than 10 records.

  • Minimize text, maximize substance. For example, if you chose PostgreSQL, briefly state why. There’s no need to list every reason for rejecting alternatives such as SQL Server or Oracle.

  • Readability is more important than format. A couple of sentences written in a free-form style will often be more useful than strict fields completed solely to satisfy a formal template.

  • Focus on relevance. The relevance of records is more important than their volume or strict adherence to a particular format.

What an ADR Should Actually Contain

  • Decision date. Keep records in chronological order.

  • Title. Provide a brief description of the decision.

  • Employee name. In a couple of years, the employee may still be working at the company. Even if they are not, the name may make it easier to find colleagues familiar with the project and its history.

  • Decision description. Explain what was decided.

  • Constraints. If the decision was non-obvious or driven by particular limitations, record them.

  • A link to a specific class, if necessary. For example, if you decide to use Redis for data caching, you can specify the RedisCacheProvider.cs class. This may seem redundant, but it puts the ADR in the context available to GitHub Copilot, helping it understand the project’s architectural decisions.

  • A unique record ID. The ID and title can be referenced from XML comments—for example, in RedisCacheProvider.cs. This can also make working with Copilot more effective.

Example

# ADR-002: Choosing Redis for Data Caching

## Date

2025-01-23

## Author

John Smith

## Decision Description

We have chosen **Redis** for data caching because it fully meets our requirements:

- High operation speed due to in-memory data storage.
- TTL support for managing data expiration.
- Reliability and fault tolerance proven by years of use in our department.
- Existing infrastructure for Redis is already deployed and configured in both testing and production environments.

The class `RedisCacheProvider.cs` will be used to implement caching in the project.

## Consequences

- Potential limitations in memory consumption for large data volumes.
- Minimal risks, as the team already has experience working with Redis.

Conclusion

If you have a small project or don’t have enough time for documentation, simplify ADR maintenance—but don’t abandon it altogether. ADR records can be genuinely useful to new developers, GitHub Copilot, and the employees who will work on the project in the future.