In my current project my function title is Software Architect. I have mixed feelings about this. While it definitely looks good on a resume I actually don’t feel software architect is a function title. Software architect is in my opinion a role, and one that can’t be handled by someone that doesn’t have his or her’s boots on the ground where the software development happens.

This is reflected in many teams where there is an 'architect' that, every now and then, comes down from his golden throne in his lofty ivory tower to enlighten the code monkeys software engineers with his architecture. After enlightening the engineers he again ascends the thousand stairs to his throne to work on his next perfect work.

Another word for this is a seagull architecture; architects that, like seagulls, fly down cover everything with shit and then fly off again. Leaving the software engineers wondering what they did wrong in a previous life to deserve all this. And if you’re lucky you don’t have a single seagull to deal with, but a whole team of them with conflicting ideas on the direction your teams should take.

Unfortunately we can’t do without architecture. Most of us don’t work in isolation. The larger the piece of software you are working on the more 'stuff' is happening outside your field of view that still impacts your work. So what is architecture? A nice quote:

That’s what software architecture boils down to; trying to predict the future as best as you can for the stuff that matters; the things that are hard to change later. And who can do that better than the experienced engineers who will have to deal with the fallout of making the wrong decision? Engineers; yes. A single 'architect' working in isolation won’t work. Even when you have one person with the explicit architecture role, you still need to buy-in of the other engineers. It’s nice that you as an architect have a brilliant idea but if the rest of the engineers aren’t buying it, it’s not going to happen.

This is what you see with most Ivory Tower architects; their ideas simply get ignored and worked around.

So if we have determined that we need architecture and that who is responsible for it, how are we going to approach it?

So what we do as architects is, as a group that straddles the boundaries between teams, make decisions that in the long run benefit the organisation and the people working in it. Those decisions need to be recorded somewhere. Some of them, the cross cutting ones that affect all teams, fit well into a software guidebook. Others only affect the individual applications.

What matters most is that they are stored in an easy to read, easy to write manner in a location near where they are used. You can write stuff in powerpoint and then upload it to confluence (confluence is where knowledge goes to die), but no one is going to read it. A software guidebook, or architecture guidebook, is a living document that changes over time. Part of this document are the rules decided upon, which we record in their own special place.

So, in my opinion, the best way to do this is to have one simple text document per decision in the repository it applies to. Whether it’s just text, Markdown or Asciidoc (I prefer the latter) does not really matter as long as you follow a consistent pattern.

While the concept by itself is easy enough to use, there’s also some tooling that can make it even easier! I recently started using ADR Tools, a simple command line tool that can create these ADRs for me in a consistent manner. And what’s especially nice is that it can mark outdated ADRs for you as well.

Many of the decisions you make as a software engineer have a long term effect. These decisions, the ones you want to get right as much as possible because they can be hard to change afterwards, are what architecture is about. Keeping this all 'in your head' does not scale beyond a very small team and documenting these on a Wiki like confluence is as frustrating as futile. So why not keep these records, little pieces of documentation, with the source they are documenting. This has the additional benefit of them following the exact same history in your VCS as the rest of your code.

Where you keep the overall decisions that apply to every single project is up to you. I’m personally a fan of keeping a Software Guidebook where these decisions are recorded as well. Another approach is to keep track of your own tech radar on what technology to adopt or avoid. All three of these approaches, architectural decision records, a software guidebook and a technology radar, integrate together really well.