Architecture Decision Records: The Fastest Way to Document Your Application

We can create a lot of software in a short amount of time. However, code is not everything and there are many important aspects of our application we can’t find in the code. If we document the decisions we make today, then we have a written explanation to help our memory in all those cases where we can’t remember the details. Instead of guessing, we can find answers quickly and persist our knowledge.

These are the important questions we try to capture:

  • What problem did we solve?
  • Why did we choose this solution?
  • What alternatives did we try and dismiss?
  • What improved by using this approach?
  • Did we increase the technical debt?
  • Did we knowingly closed options we had before?

Many developers fear a monstrosity of documentation with an uncountable amount of pages written to answer each of those questions. You certainly can do that. But there is a much leaner approach: Architecture Decision Records (ADR).

 

What is an ADR?

Michael Nygard introduced the idea of ADR in this blog post. The whole post is an ADR about ADR and shows that you do not need to write a lot to introduce new concepts. Your decisions may not be so fundamentally new and you can explain them in fewer words.

The ADR template by Michael Nygard has these sections:

  • Title: short present tense imperative phrase, less than 50 characters, like a git commit message.
  • Status: proposed, accepted, rejected, deprecated, superseded, etc.
  • Context: what is the issue that we are seeing that is motivating this decision or change?
  • Decision: what is the change that we are actually proposing or doing?
  • Consequences: what becomes easier or more difficult to do because of this change?

Joel Parker Henderson collected in his Git repository more complex examples of ADR templates. The one by Jeff Tyree and Art Akerman includes constraints and artefacts, while the template for a business case has a place to put your SWOT analysis in.

Those are just two additional templates that show how you can scale up your efforts to document your application. If you have the need, ADR can help you. However, do not use those complex templates if you do not need them. Small and simple is more sustainable than big and complex.

 

Tools

The format is so simple that you do not need tools to work with ADR. However, creating those entries in the right order and using the right template may be simpler with the adr-tools. This is a bash script, but you can get a client in C# or Java if you prefer those languages.

 

Added Benefit: Persist your knowledge

As part of your development process you have answered those question at the beginning of this post. You had to weigh up your options and settled for one specific approach. You did all the hard work, the only thing left is to write an ADR entry and you are done. That will not only persist your knowledge, but it can help you later to explain why you took a certain path. Had you considered library X? If so, write it down as one of the alternatives you checked but did not choose. If 6 months from now someone wants to know if you examined this library, you can answer this question with a yes and deliver the reason why you did not use it – all that without spending time trying to remember the details.

 

Alternatives

The arc42 template for documenting your architecture has a similar approach in the chapter on Design Decisions. You can use the format as explained above or go with the one from the arc42 template. How you capture the information is up to you. The important part is that you write it down and that everyone in the team does it the same way. Otherwise you constantly need to switch between different formats and that is a time waster.

 

Conclusion

Documenting design decisions does not need to be a lot of work. With ADR you get a simple format that can capture the important aspects without spending more time on the documentation than in your code. Give it a try and start persisting your knowledge about your application.

2 thoughts on “Architecture Decision Records: The Fastest Way to Document Your Application”

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.