With all the agile software development movement, the role of the architect has changed to some degree as well.

While exploring the full breadth of changes is an interesting (some might say tedious) discussion, one of the most prominent challenges I often face is finding an efficient way to preserve knowledge around design/architecture decisions that are made in a project.
It’s a challenge I faced when I joined a team already working on several different products, and me being the new guy (and the one who’s supposed to make design decisions!) – I had to spend considerable time researching, asking around, digging into code and old presentations, trying to figure out why the system was built the way it is. In some cases there was actually no clear answer.
It’s also a situation I expect people to face with any long-lived project/product development. Unless you maintain very good documentation of your design decisions,  it will be hard to trace back why things are built the way they are. I know I’ve faced similar situations in past projects.

Documenting decisions is tedious. Moreover, it’s often perceived as non-productive. It doesn’t add product value. But even that – convincing people to document design decisions – is the easy part in my experience. The harder task is to actually write something that is coherent, describes the context and the decision succinctly but completely.

One methodology I found, liked, and currently experimenting with, is that of Architecture Decision Records.
Refer to the link above for a complete overview, but in a nutshell: describe your architecture decision using a simple template, keep one file per decision, keep them with the source code, and setup a minimal process around these decisions, to be reflected in the files. The coupling to the code, and focus on specific decisions, is what I think will make this a more productive way to document our design decisions.

For me, at this point in time, this is still in “POC mode”. I’ve introduced it to my team, and currently pushing it, but we still need to see more value.

One thing I missed from the beginning is a way to to easily setup and manage ADRs. I found this open source project, which seems useful. But it’s based solely on linux shell scripts. Being mostly a windows user in my day-to-day work, I missed a good windows integration.

And thus the ADR Flow project was born.

The ADR Flow tool is meant to be a simple command line tool to aid in the process of creating and managing the ADR lifecycle. It’s meant to be simple enough so that it could be easily integrated into any workflow and/or standard tool.
It is not meant to hide the fact that ADRs are text files, or prevent editing them in whatever tools the user sees fit. Rather it tries to leverage some of the maintenance overhead, and make managing ADRs easy.

It’s a fun side project, also giving me the option to explore more possibilities for development with Node.js.

Comments, questions, feedback and of course contributions are more than welcome.