The whiteboard paradox: perfect for brainstorming, terrible for visibility

Remember when Jane Manchun Wong made fun of the infamous 2022 “Twitter code review” post?

What still stands out to me (besides how bad AI-image generation was in 2022) is how it immediately highlights all the most painful aspects of working with whiteboards.

Don’t get me wrong, when trying to understand a complex distributed system there is nothing better than having someone knowledgeable walk through each part with a visual diagram. However, a drawing becomes immediately obsolete once your system changes in any way. It also provides an excellent top-line visual but contains none of the underlying data or context needed to make contextual software development decisions.

As a starting point, a whiteboard can give you a good overview of a company’s architecture and it’s great for sketching concepts and ideation, but going back to it every time you need to add a microservice or change a feature is not sustainable.

Is it a Leonardo da Vinci or a Jackson Pollock?

Have you ever been in a whiteboard session where the diagram gets so complex that explaining it feels like you’re doing an interpretive dance routine? Or your picture looks like a battle map from Game of Thrones?

The opposite might be true as well: you’re reducing an intricate distributed system to abstract blobs and squiggly lines, which lack the necessary level of detail or precision to faithfully represent it. How do you capture all the elements, relationships, components, and even background decisions and context with just a set of colored markers?

Problems of completeness aside, we still have to contend with imperfect memories and evolving systems. Your tour guide to this maze might not remember all the twists, turns, and abstract symbols correctly, especially after the last few pull requests were merged.

Lastly, we cannot diminish the importance of context: if you were not part of the conversation around a specific feature or bug it’s very likely that sections of the whiteboard will elicit more questions than answers.

The documentation disappearing act

We’ve already gone into detail as to why architecture documentation is painful and whiteboards are a perfect example of diagrams that are static, inaccurate, incomplete, inconsistent, and not interactive.

The best-case scenario is that someone snaps a picture of the whiteboard and adds it to a document. Bonus points if they try and reproduce it with an online diagramming tool. However, this would require interpreting the "chicken scratch" writing and guessing at what some of the less discernible scribbles were supposed to indicate.

Notwithstanding the fact that this is rarely done at all, whiteboards lack the ability to have version control, making it difficult to track changes and review the evolution of ideas or designs over time.

In other words: you will likely never uncover why a specific design decision or architectural change was made from just looking at a whiteboard.

Fitting an elephant into a teacup

Trying to squeeze a large-scale distributed system, with all its numerous components, interactions, and dependencies, into a static image, is like trying to fit an elephant into a teacup.

Whether you have a single standing whiteboard or a digital drag-and-drop whiteboard, you still may end up with a "Star Wars death star" type of diagram.

It’s also a question of limited time: how much ground can you cover in a single meeting, while manually re-drawing and erasing things the whole time? Or, how can you ensure everyone on the team is up to speed on the different components?

Architecture whiteboarding sessions are known for turning into marathons, with super interesting (but ultimately tangential) deep dives or religious debates about an approach or programming style. Having these discussions centered around a static picture isn’t an effective way to collaborate. It just leads to a bunch of additional follow-up meetings with different subsets of people that have to happen before final decisions can be made.

The collaboration conundrum

If you work on a distributed team (whether remotely or across multiple offices), you are familiar with the Olympic-level calendar gymnastics needed to find a time when everyone is free, and in the office at the same time, and the “good” whiteboard room is available.

However, at the last moment, John needs to stay home, so now you need to set up the video conferencing. And then the shenanigans ensue:

“I didn’t mean connect those to boxes, I meant the other two on the left…”

“Can you write neater and larger please, I can’t read your writing …”

“Oh no, we forgot to invite [insert here the only person who knows why a specific architecture decision was made]…”

Instead of a physical whiteboard, it's likely that you use a web-based drag-and-drop whiteboarding tool... but the underlying problem remains the same: unless you have a diagram that’s accurate, interactive, and connected to your live system, you’ll still encounter issues with information gaps and misunderstandings.

Beyond the whiteboard: living system documentation

Whiteboards serve an important purpose: they're unmatched for initial brainstorming, explaining concepts to newcomers, and collaborative ideation. But they were never designed to be the source of truth for complex, evolving distributed systems.

The fundamental problem isn't the whiteboard itself; it's that we've been trying to use a tool designed for temporary exploration as real-time visibility into an ever-changing system.

What engineering teams actually need is system visualization that updates automatically as the architecture evolves, captures both high-level topology and granular detail, and provides the context behind design decisions. Instead of asking "How can we better maintain whiteboard diagrams?" the better question is "Can we eliminate the need to manually maintain system diagrams at all?"

Tools like Multiplayer automatically create and continuously update comprehensive system visibility, leveraging the telemetry data your system already generates through OpenTelemetry.

Deploy a new service? It appears immediately. Modify an API? The diagram updates in real-time. Change database dependencies? The visualization reflects it without anyone touching a marker or updating a diagram file.

This doesn't replace the value of whiteboarding sessions for exploring new ideas. It just replaces the impossible task of keeping those whiteboards accurate as your system evolves.

The whiteboard was a brilliant tool for the problems of its era. But distributed systems have outgrown what static diagrams can deliver. It's time to let your system document itself.