The worst advice on diagramming I've ever read

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 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 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.