Follow-up: How architecture diagrams enable better conversations

My previous post was pickup and shared on Hacker News, there was lots of really good discussion in the comments, and there were a number of points raised which I thought would make a good follow up blog post.

There were a few main themes in the comments:

• There was broad consensus that architecture diagrams are helpful/useful for teams
• There were lots of different tools/methods that people use for architecture diagrams, although a reasonable number have used/use C4
• Diagrams are expensive or difficult to maintain
• Blog post about architecture diagrams, without any diagrams!?

I wanted to touch on a few of these points and share a few more thoughts and reflections prompted by the various comments.

Strategies for sustainable architecture diagrams

It’s my position that with the right mix of skills/abilities and mindset you will be able to have architecture diagrams that are not only useful early on in a project but will last up until the point that you decomission that thing running in Production.

Maintain your diagrams (or throw them away)

One of the commentators from Hacker News made the following point:

"[…] Once that project is done, the diagram is likely already out of date. No plan survives contact with the enemy and all that. But for this use case its job is complete and it can be discarded or archived with the rest of the planning work. […]"

Naturally there will be a point at which your diagrams will no longer be useful, this could be for a number of reason but hopefully it’s because the service/product/thing has been deprecated or decommissioned and therefore the digrams can be archived, rather than because the diagrams weren’t maintained and now the actual architecture has drifted away from what is shown in the diagram.

I think the point that the commentator is making is that generally speaking diagrams are created at the beginning of a project, are useful for getting everyone on the same page but then once the work is started they are soon forgotten and over time their value is diminished because they aren’t maintained (I hope I’ve got that right). Whilst I agree that this does happen, I don’t agree that it has to happen. The only way to avoid bit rot of our architecture diagrams is to maintain them. This has a number of implications:

• It needs to be a whole team effort
• Everyone on the team needs to understand their value
• Everyone on the team should know how to update them

Still it’s possible that even with the above points in mind that bit rot can seep in, most of us will know the saying “out of sight, out of mind” and that leads onto the next point…

Make diagrams part of your workflow

“Architecture diagrams are great and do indeed enable better conversations. They are just expensive to build, expensive to maintain and go out of date fast enough that they’re practically ephemeral.”

To avoid architecture diagrams going out of date, or drifting from reality they need to be something that you look at regularly. This isn’t necessarily every day of the week, you’ll probably also find that there are times when you are more focused on planning and therefore are spending more time looking at the diagrams. The point is that they need to be part of your workflow, as I mentioned in my previous post, one of the places I’ve found diagrams to enable better conversations was during planning of new pieces of functionality. So perhaps one way of making diagrams part of your workflow is to spend 2 minutes at the beginning of each planning meeting looking over the diagrams and refreshing everyone’s memory of what the different components are.

If you are regularly looking at your diagrams then you’ll also spot where something is missing or where you’ve put something down which isn’t accurate. However this does require members of the team to champion architecture diagrams, and for the whole team to be bought into their value. This is a place where senior engineers/leaders can step up, we can help those less experienced in our teams to learn:

• the language we use when talking about architecture (e.g. in C4 we talk about systems, containers, components etc)
• how your team/organisation documents architecture

"[…] the ivory-tower: someone somewhere created all the diagrams alone and dumps them on everyone hoping it will make the world better. The problem is that mode lacks the collaboration and mutual context-building to get everyone on the same page. Not everything needs to be a team effort, but a lot of your diagram work should shift towards a day-to-day tactical discussion (the deeper the C4 level the faster moving things will be). […]"

The whole team should:

• own their architecture / system design
• understand the architecture and be capable of articulating it (to greater/lesser extents depending on their level of experience)
• be able to maintain the diagrams

Beyond architecture diagrams - Architecture Decision Records

“One of the areas I would like to see addressed in guidance for drafting both architecture diagrams and specifications is in the documentation of the basis for design decisions. Which risks catalyzed a particular design or approach on a particular feature and to what degree?

In my own work, when I need to revisit a spec months afterwards, I often have trouble because I’ve forgotten parts of the context that I had at the time the spec was drafted. The situation is a bit like the Chesterton’s Fence where the original person that set the fence in the middle of the road has also partially forgotten why it needs to be there. It was so obvious at the time…

Do others supplement their architecture diagrams and specifications with a cross-refenced list of risks, alternatives, and probabilities?”

Something that I didn’t write about in my previous post but some of the commenters in Hacker News mentioned was the use of Architecture Decision Records (ADRs). We’ve been using them at DrDoctor for a couple of years now, the template we use is very similar to this one. The key thing isn’t so much the decision made (although that is obviously very important), the real value comes from:

• context/problem statement this ADR is looking to address
• options considered when making this decision
• pros/cons of the various options
• when and who was involved (so you know who to go and talk to about this decision down the road)

One thing that I keep reminding engineers is that the right time to start writing an ADR is when you’re early on in the decision making process. There is still value in writing an ADR when the decision has been decided, but my opinion is that the quality of an ADR is reflected in seeing the thought process that the individuals went through to make a decision.

Wrapping up

A few people commented that I’d written a post about architecture diagrams but didn’t actually include any in my post. This would be a fair comment, except that it missed the point of the post - I specifically wasn’t trying to write a post about how to draw architecture diagrams but rather about some of the benefits I’ve found being able to refer to them in different circumstances.

Yet again I’ve written about architecture diagrams without including any in my post, I hope that you will look past that and see that the points I’m trying to make are:

• architecture diagrams can last beyond a whiteboarding session/project kick off - but it requires that the whole team is able to understand their architecture and have the skills necessary to maintain the diagrams
• by regularly reviewing (or just looking at) your architecture diagrams you can ensure they stay front of mind, and make those small adjustments when you notice that something is missing or has diverged from what is documented
• architecture decision records are an excellent compliment along side architecture diagrams
• not all posts need an image (but it probably helps)