Documenting Architecture Decisions - ADR

As I reviewed the 2017 Thoughtworks technology techniques trends, one cool recommendation was about to "try" the concept of Lightweight Architecture Decision Records. I must admit, I have been looking for something like this as I'm tired of having note pads everywhere, and I'm really trying to stay away from MS-Word documents and Powerpoints for developers. I have been looking for something lightweight, easy for developers to follow.


I tried ADR-tools, and in 10 minutes I was able to document on my personal projects (my pinewood derby project, soon to be added to github). Installing was easy on a Mac:

brew install olleolleolle/adr-tools/adr_tools

Pages already contain the markup needed for github and gitlab (which is probably more than what I need). Running the command:

adr list

Lists all ADR in the local directory. Adding a new ADR:

adr new Add new Component

Creates a page and opens the editor (configured in your EDITOR env variable). Notice the markup is ready to go. Doing the following:

adr new -s 2 Add super new Component

Allows you to supersede an ADR and updates the ADR markup pages automatically. This is a sample of a superseded page:


This is a superseding page:


Documenting architecture decisions may be harder than most people think, and I'd concede that this approach may be too simplistic, and almost impossible for monolith apps. In designing and archictecting systems, I'm finding that in the process of "innovation and creativity", if I can't describe a system, or tell the story or how we got "there", I'm simply over-architecting.

I'm going to continue to experiment with this small tool, however I'm already feeling like I may have found something useful to keep up with my architecture decisions.