Hey Developers: Diagrams Don’t Need to Be So Complex

Let’s put it simply: we’re overthinking our diagrams.

Creating diagrams is an important part of the code documentation process. Unfortunately, it’s usually seen as an arduous and time-consuming chore. Diagrams quickly become too granular and too detailed. The most important details are lost in a sea of complexity.

In an effort to reduce ambiguity in their UML diagrams, developers often establish specific symbols or standardization for reading the diagram. Suddenly, your diagram becomes so filled with symbols that it requires a whole layer of knowledge just to read. You’ve effectively ended up coding within the diagram. And unless you’re building a thousand-page visual, it’ll never express the level of detail that your code does. 

The sentiment is a good one; “I want my diagram to be as exact as possible.” But instead of reducing ambiguity, you’ve actually increased it. Some of this can be blamed on the over-complication of UML itself — but developers like us can be a part of the solution.

Overloading diagrams with excessive information can blur the intended message and confuse the reader. We should become more aware of these downsides. In our pursuit of details, developers must not lose sight of our core objective: effectively communicating a concept.

Diagrams should contain enough information to be useful and still be easy to read. They should help teams communicate the big-picture details of a complex software system — or the finer ones. And they should be easy – and even fun — to make!

With a collective mindset shift, new diagramming tools, and an emphasis on helpful integrations, we can get diagrams back to being effective vessels for transferring information between writer and reader. Re-simplifying the process will help us make diagramming fun again — and it’ll set us up for better communication in an AI-driven workplace future.

UML Didn’t Live Up to Its Expectations, but It’s Not Totally Useless

The overcomplication of diagrams can be traced back to the unified modeling language (UML).

I myself have written about UML’s follies. The UML 2.2 documentation was over 1,000 pages long, which is why UML became associated with inconvenient and often wasteful pre-work.

While it fell short of becoming an all-encompassing language for software development, UML still leaves an important legacy. We shouldn’t use flowcharts, state diagrams, sequence diagrams or flowcharts as a replacement for our code or as hard blueprints. That requires too much overhead.

These diagrams are, however, extremely effective as high-level sketching tools. UML peaked as a medium for sketching a system around 2000. Just like a fashion trend, it’s coming back in style.

“Comprehensiveness Is the Enemy of Comprehensibility”...

That’s a quote from Martin Fowler, who helped popularize UML in the 1990s. Maybe it’s time we listened!

Diagrams can’t — and shouldn’t — capture all of the information about a system. They’re often best used for high-level tasks: visualizing how a system is used, diagramming the logical flow of a process, or mapping out the functionality of a service. They can help us communicate how systems talk to each other, describe how systems operate internally, identify areas where our models can be simplified, and so on. Effectively, they help us turn black boxes into glass ones.

…But Balance is Essential

Details are still important for code documentation; it’s just about prioritizing what’s most essential for your reader. A diagram that’s too light on details becomes useless, as well. Sometimes, it’s just about how you present those details.

Perhaps you want to create a diagram about a specific, complicated, low-level detail within your code. Visuals and charts can still be incredibly helpful. But maybe it’s better to create a separate diagram that goes into the nitty-gritty of that specific procedure. That way, you’re not overcrowding one diagram with all of your information; you’re breaking it up in a way that makes sense and allows your team members to choose how deep they’re diving into different parts of your code.

Three Keys to Bringing Diagrams Back to Basics

A combination of human behavior shifts and helpful software can help us increase our collaboration through diagramming:

A Collective Mindset Shift on What Diagrams Are Used For

Diagrams often fail when they’re overly complicated — or overly simplified. But they’re also a mode of communication. It can seem counter-intuitive to remove information when your goal is clear communication.

But too much information is the biggest enemy of clarity. That’s what we have to remember collectively.

Before you create a diagram, try to understand what you want to articulate fully. Are you looking to give a high-level overview of the entire system? Or do you want to dive deep into a specific part of your code? Make a game plan and have a defined purpose for each visual. And don’t worry if all of your information doesn’t fit into one diagram. You can always make another.

Tools That Promote Better Diagramming

Part of the blame for ineffective diagrams falls on the diagramming tools at a developer’s disposal. Designing diagrams with PowerPoint or other “click and drag” tools can be difficult. They might even encourage a certain way of thinking: if I’m spending all this time building a diagram, I might as well include as much information as possible.

That’s why developers need to invest in diagramming tools that help them quickly and easily generate diagrams. Creating visuals should be simple and fun. When this is true, developers won’t hesitate to make multiple, smaller diagrams that are tailored for a specific purpose — instead of trying to stuff everything into one visual so they can move on.

More Integrations To Make Life Easier

If you thought I’d go the whole post without mentioning artificial intelligence — I’m sorry. Incorporating generative AI into our diagramming tools can make life much easier for developers. A tool such as ChatGPT could help you get to a baseline diagram faster. All you have to do is add more specifics and a human touch.

We could also benefit from integrating diagramming tools into our coding tools. If a diagram can live closer to its source code (instead of in an entirely separate program or window), then developers won’t worry about having to communicate so much within the diagram itself. The more connectivity, the clearer the role of the diagram becomes.

The Future: Diagrams, Documentation and AI

Diagrams are most effective when they have a clear purpose for what they’re communicating. This is really important when we look at the future of work. 

Artificial intelligence will continue to handle more specialized roles. That leaves humans to focus on what they do best: managing processes, enhancing products, and thinking up new ideas. As more processes become automated, it's important that we set a clear direction with our human colleagues before each project. We can only accelerate innovation if we continue to communicate. 

Diagrams help us communicate essential details with our colleagues, making them an important part of how we’ll collaborate in the future. Striking the right balance of complexity and simplicity in our diagrams will only become more important.