Keeping a Record of Software Architecture Decisions

Home » Blog » Software » Keeping a Record of Software Architecture Decisions

The need for asynchronous communication in organisations has become particularly obvious since 2020, when remote work and distributed work environments rapidly became the default setting for knowledge workers.

Asynchronous communication essentially means that instead of exclusively communicating objectives, goals and the way by which to achieve them in-person (i.e. synchronously with everyone involved present at the same time – whether on-site or in a virtual space such as Slack or Zoom) we try and keep a digital record of decisions, the decision process, and any other information relevant to the completion of a task. This allows stakeholders to access this information whenever they need it.

It’s not like only with the advent of remote work as a widespread phenomenon asynchronous communication became necessary, though. Rather, as with various other aspects of how we organise work, remote work has worked as a catalyst for much needed change:

In contrast to toxic habits such as frequent, repetitive meetings or haphazard water cooler talk, asynchronous communication helps with avoiding information silos and making information explicit. This has been true since long before 2020. It’s just that before 2020 organisations could afford to indulge in the laziness of compensating for the shortcomings of their documentation processes (or more often than not: a lack thereof) by regularly having everyone involved in a task or project meet in the same room to make sure they’re on the same page.

Asynchronous communication is of particular importance in the software industry because software development particularly lends itself to distributed work processes. Software development by its very nature is a distributed and asynchronous process.

Therefore, I’d like address an area of software development where decisions can have both far-reaching and long-lasting consequences: Software architecture and architecture decisions.

Almost 10 years ago now, software developer Michael Nygard wrote an article
on Documenting Architecture Decisions, in which the author advocates for the use of architecture decision records (ADRs) as a way of making decisions about the architecture of a particular software product explicit. In a self-referential, meta kind of way that article itself is an example of such an ADR.

The ADR format as outlined in the article comprises title, context, the decision, its status, and a discussion of the consequences. According to the approach proposed in the article, ADR documents are treated as first-class citizens and hence are to be kept as Markdown files in the version control system alongside with the project’s source code.

While Michael’s proposal certainly isn’t the only one of its kind and there are many similar templates, it’s a useful and proven approach that’s worth emulating, especially if your organisation doesn’t explicitly document software architecture decisions yet.

About the author: Bjoern
Independent IT consultant, entrepreneur

Leave a Comment