Visualising ADRs

I'm a big fan of architecture decision records (ADRs) - a collection of short text files, stored in version control, that provides a way to document the significant decisions made before/during the development of a software product. I highly recommend that all teams adopt this lightweight practice, and they are a core part of my minimal approach to software architecture documentation. For tooling, I really like Nat Pryce's adr-tools command line utility for managing ADRs.

Do team members ever look at that folder of ADRs though? And how easy is it to search for information related to a single decision, or perhaps even a chain of decisions? Something we could really do a better job of is visualising those decisions, making them easy to find and read.

Structurizr has supported publishing ADRs for a while now, and I've just added (an initial version of) a feature that visualises ADRs as a force-directed graph, showing the decisions and the connections between those decisions where they've been superseded. Here's a screenshot showing the decisions related to how the Structurizr cloud service has moved from Rackspace to Pivotal Web Services, and then onwards to Amazon Web Services.

If you have a folder of ADRs created using Nat's tool, you can get this visualisation for free with Structurizr Lite in under 5 minutes.

1. Create a workspace.dsl file

Create a file named workspace.dsl next to your folder of ADRs.

Add the following content to that file.

This says, "create a workspace, and load the ADRs from the decisions sub-directory".

2. Start Structurizr Lite

Assuming that you have Docker installed, you can now start Structurizr Lite with the following commands:

Be sure to replace PATH with the full path to the directory containing your workspace.dsl file.

3. Open Structurizr Lite

Open the workspace in a web browser by heading to http://localhost:8080 and you should see your decisions.

You can now click through the decisions, and press the Space key to open the quick navigation feature. Click the little graph button underneath the heading, and the visualisation will open.

Over time, the graph will start to change to reflect how decisions have been superseded, deprecated, etc.

Summary

As I said at the start, I'm a big fan of ADRs. Whether you're using Structurizr or building your own tooling, we can do better than keeping them hidden away in a folder.