I’ve recently come across this advice for diagramming system architectures:
“Prioritize abstractions over details: Abstract information is still correct, it’s just leaving out some detail. Leaving out details reduces the chance for errors and the need for constant updates. Have the courage to leave things undocumented (better no documentation than wrong documentation). Document only those parts or aspects of your system and its architecture that are definitely required by stakeholders.”
It struck me HOW WRONG this advice is.
I started to explain to my colleagues why this was such a disappointing (and counterproductive) advice but there was just SO MUCH wrong about it.
So here’s a blog post.
1^ Wrong Thing: Over-prioritizing Abstractions
I understand the intrinsic value of abstractions to quickly and effectively explain complex concepts. I also completely agree that when brainstorming or explaining a system it makes sense to rely on abstractions.
That said, arguing that your documentation should prioritize abstractions is a recipe for misunderstanding, frustration, and, ultimately, useless docs.
Over-prioritizing abstractions means you omit key information that are necessary to understand how a system operates. Furthermore, without sufficient detail, developers and other stakeholders risk making flawed assumptions about how components interact, leading to incorrect architectural decisions.
Not to mention that when something breaks, overly abstract diagrams don’t provide the actionable information needed to locate and resolve issues.
In short, you may use your abstracted diagram during the first day of onboarding and nothing else, because already on the second day your new teammate will have more questions than that diagram can answer.
2^ Wrong Thing: Leaving Out Details
Modern distributed systems—effectively most systems nowadays—involve intricate dependencies, APIs, and external integrations. Omitting details makes it nearly impossible to map how systems truly behave in production.
“Leaving out details reduces the chance for errors and the need for constant updates.”
What are we optimizing for here? What is the purpose of this document? Is it just to check a box?
It sounds like advice for how to spend the least amount of effort on writing a must-have document, that you have to touch the least number of times. Again, who is this serving?
Architectural documentation—diagrams included—should be in service of helping engineers (and various other stakeholders) understand their system.
If we assume that this diagrams has to be useful, then it has to be accurate, thorough and updated.
I’ve written ad nauseam about the reasons why documentation is painful, and most recently I’ve reached the conclusion that traditional documentation practices will always fall short.
But there ARE WAYS TO KEEP DETAILED DIAGRAMS updated, least of all using tools that use your own system as the source of truth.
3^ Wrong Thing: Assuming Diagrams Are Always Outdated
As long as we continue to use diagramming tools built for static images instead of purpose-built for developers, we will continue to see diagrams as a burden.
When you have to constantly battle with arranging boxes and connecting arrows — knowing that at the next PR your perfectly designed diagram will already be out of date — of course the advice is to make it as “abstract” as possible so you don’t have to waste as much time to update it.
But the truth is that dynamic, accurate diagrams are possible.
Modern tools make it possible to create diagrams that evolve with your system, maintaining accuracy and reducing manual overhead. For example, Multiplayer’s System Auto-Documentation can address the challenges of keeping documentation up-to-date without sacrificing detail.
4^ Wrong Thing: Assuming Info can be Found Elsewhere
If the diagram of your system architecture is incomplete / outdated, then where do you expert your engineers to find this information?
I can already hear the comments: “Just read the code”. Which goes hand in hand with the good old “self-documenting code” myth.
It’s not bad advice per sé, it just assumes that you (a) have the time to read, understand and reverse-engineering how the system works and (b) have the knowledge to do so (remember, there are many stakeholders that benefit from understanding how a system works, engineers are only one of them).
But let’s assume that (a) and (b) are not a problem for you. Let’s also assume that team turn over, tacit and tribal knowledge are also not an issue when it comes to institutional knowledge.
How about the frustration of looking for information where it should be (documentation), not finding it, having to search for it, maybe having to ask a colleague, having to wait for an answer,…
Context switching fatigue is real.
5^ Wrong Thing: Encouraging No Docs Over Wrong Docs
We all know that documentation is a task that often ends in the backlog or that outright ends fully ignored because of tight deadlines, GTM priorities, etc.
Saying "Better No Documentation Than Wrong Documentation" is like saying that you can confidently rely on tribal knowledge. Tribal knowledge is a good resource, but it cannot be THE ONLY resource to understand the system architecture.
An attempt at documentation is always better than no documentation, at the very least as a historical snapshot of the system or the architectural decisions made in that moment. It’s a starting point for understanding the system. Teams can cross-check it with the current state and update it as needed. Having nothing to reference makes it harder to orient new team members or debug issues.
Saying no docs are better than wrong docs, is like saying no wifi is better than slow wifi. Slow wifi is very (VERY) frustrating, but at least I can get SOME work done.
But this point is wrong also because it effectively says that you shouldn’t build a culture of documentation unless the outcome is accurate documentation.
Indeed you should build a culture of documentation even if you may be using sub-optimal tools and processes at first because documenting your design decisions, trade offs, architectural conversations is worthwhile and it serves your long-term project longevity.
Conclusion
I honestly could go on.
For example the sentence “Document only those parts or aspects of your system and its architecture that are definitely required by stakeholders”. Which stakeholders? Developers have different requirements than DevOps, QA, PMs, Managers, etc. Is the recommendation to create an individual diagram tailed per stakeholder group?
Again, another issue that could be solved with a dynamic diagram and using the right tooling.
I don’t mean any hate towards the author of this advice. In fact it was within an article that presents other useful tips on diagramming.
However, what bothers me most about this advice is that it reflect an outdated view of diagrams and documentation - it views them as an artifact that you have to create, maybe as part of a top-down, ivory-tower style architectural process.
It assumes and accepts that documentation is painful and it tries to minimize the effort involved.
Instead, I believe developer tools and practices have advanced enough to allows to have our cake and eat it too: be able to document our systems in detail and in real-time without having to sacrifice large amount of time and effort.
Top comments (0)