Why is documenting architecture hard? (1/10)
What does your software architecture look like? And if you know, will your peers agree with you and draw the same diagram the same way? Is there some hidden truth that isn’t in your diagram? Are you confident enough in it to start onboarding new developers with that or do you need to warn them about your documentation first?
I talk to a lot of software teams about their architectures, and I regularly see some form of challenge with creating clear diagrams from the vast majority of them. Some have invested heavily in one standard for documenting, others have a process where they defer everything to a “Chief Architect”, and others draw diagrams that are some kind of bubbling frothy mess of whatever ideas were in the head of the person with a whiteboard marker in their hand at the time.
Software is complex — but so are other fields that don’t have these issues. Why can we make blueprints for skyscrapers or aircraft, have schematics for complex electronics, yet somehow software architecture diagrams is still more of an art than a science? I’ll decompose this problem for you right now, and then I’ll show you how to handle it.
Too many conversations at the same time
When you ask an arbitrary developer at an arbitrary company to diagram their architecture, a mental dam bursts and a deluge of ideas floods the whiteboard. You can even spot when this happens because the diagrams will look like a mess of unlabeled boxes, sometimes nested, sometimes with arrows, sometimes without arrows, strange looping arrows, and usually something that crosses over everything like a layer or a horizon.
So why did this happen? When we think about our software we’re storing the entire thing in our heads in an unstructured or unexplainable mess (and we often later on ask ourselves “how did our software become unmaintainable?”). If you run a mental debugger and start to pull the ideas apart you’ll see the average developer is keeping multiple intersecting dimensions in their mind at the same time: a form of “multidimensional architecture space“. You might have even run into a developer who wished they could diagram things in 3D or 4D to explain the architecture (hint: that wouldn’t help either — you will find out if you read the rest of this series).
So what are these dimensions once unpacked?
Structural (Write-time; when you write it)
Temporal (run-time; when you run it)
Abstractions and Concretions (think-time)
Assumed Environment (tacit-time)
Human Communication (story-time)
Each one of these exist in their natural environment as a curled up tangled mess with one another. Developers must learn how to untangle and re-structure these in order to create clear and understandable diagrams. In this series of posts I’ll take you through each one in detail, and end with both general advice and concrete “sane defaults” to help you get your diagrams working.
We’ll discover there are two truths and three guiding rules to use which let you create a good diagram:
Truths about using diagrams:
You are using a language to communicate.
You are telling a story to a real human.
Rules for creating good diagrams:
Only write the stories that need to be told.
If you tell more than one story at a time, you will write one bad story.
Not everything needs to be in the main plot-line of your story.
At the very end I’ll offer a set of very concrete tips that won’t work for everyone but generally solve 80% of the problems I see people run into when they create an architecture diagrams.