If You Love to Code, You Should Also Love Making Diagrams
When diagrams are easy and fun to build, we unlock greater collaboration and communication
November 01, 2023

Knut Sveidqvist
Mermaid Chart

“I love making diagrams for my code!”

If you're a developer, it's pretty unlikely you've heard any colleagues utter these words.

In general, we developers recognize the importance and utility of using diagrams to design systems and document our code. Diagrams help turn black boxes into glass ones. They can help us describe how systems talk to each other, communicate how systems operate internally, identify areas where our models can be simplified, and so on.

The process of actually making those diagrams, however, is another story. Clicking around in a graphical user interface (GUI) can be a time thief — and it can sometimes take several minutes just to find the right file. When the creation process is difficult, developers might be more likely to either a.) stuff too much information into a single diagram to avoid making multiple diagrams or b.) oversimplify their diagrams so they can more quickly get back to their code.

And what if something in the diagram needs to be tweaked or updated? The process starts over again, and we're spending more time further from our code.

I'd understand if you find the process of making diagrams to be a little clunky and clumsy. However, you probably recognize the power of correct, clear, and up-to-date diagrams to complement your code. So how do we bridge this gap?

Better diagrams are part of the future of development. With the right methodology and tools, we can make creating diagrams easier and more fun. Developers should be leaning into automation so that they can focus more on the accuracy of diagrams than how they look. Easy functionality should make it easy to find a balance between clarity and comprehensiveness — and diagrams should be easy to access directly from our codebases.

This movement will hopefully lead to increased alignment within organizations and better user experiences. And who's to say non-developers can't join the diagramming fun? When it's truly easy and fun to create visuals, professionals across functions can start using diagrams to convey complex ideas and collaborate with colleagues. It might just change the way we communicate in the workplace altogether.

3 Steps to Make Creating Diagrams Easier - and More Fun

Let's explore how we can make this possible:

1. More automation, less design

I think I speak for many developers when I say that designing a diagram is often my least favorite part. My real love is coding, not deciding the right colors or icons for my next diagram.

That's where we can lean towards generative AI-enabled tools to help us automate the creation and design of the diagrams. Let AI make it pretty — we'll focus on the content. That's the democratizing power of artificial intelligence.

2. Establish a balance of clarity and comprehensiveness

Diagrams aren't meant to capture all of the information about a system. They're best used for a specific purpose, whether that's providing a high-level sketch of your system or augmenting a specific, complicated detail within your code. It's all about balance; relaying the right amount of information without confusing the reader.

I think the developer community can do a better job of understanding what they want to articulate before they start rendering their diagrams. Don't fret if all of your information doesn't fit into a single diagram. You can always make another: especially if your tool is easy to use.

3. Reduce the distance from code to diagram

We've all experienced the hassle of changing a diagram with traditional tools. Even a simple change such as a renamed server forces you to update your diagram to avoid relaying outdated information.

Traditionally, you'd have to stop working on your code, go to a different platform, find your Visual Studio file, open that up, make your change, upload the file, etc. It's way too cumbersome.

We should be incorporating diagrams directly into our codebases. Think of how much more enjoyable it would be if you could view, edit, and update diagrams within your code editor.

What Do We Unlock with Better Diagrams?

A few changes to our workflows can produce some seriously beneficial results:

Greater alignment for developers and beyond

Clear, concise, up-to-date diagrams can do wonders for team alignment. Developers can hand off work to one another with relative ease. There'll be fewer hiccups and miscommunications when everyone's on the same page about the design.

This impact can extend beyond technical decisions. When everyone has a common understanding of how things work, business results tend to follow.

Enhanced error recognition and modifications

Bugs and errors slow down projects. Better diagrams can make recognizing and fixing these hiccups easier. When you've adequately mapped the flow and process that your program uses, you can zoom out and identify which module or message is problematic.

Additionally, diagrams help when you're returning to the code you created months ago. It's much easier to figure out what the code does, and in turn, to make modifications in line with the functions.

Diagrams Can Drive Better Collaboration and Communication

The current problems with diagramming are emblematic of a larger issue in the working world; we're wasting too much of our time on tasks that drain us of energy.

According to data from Asana, employees spend 58% of their day on menial tasks such as work communications, switching between apps, and chasing status updates. Only 33% of our time goes towards “skilled” work and just 9% is left behind for strategic work towards major goals.

Managers and company leaders should do anything they can to alleviate some of this busy work. Tools that can help streamline communication — without being overly complex — have a role to play.

Diagrams can help us collaborate and communicate better. That leaves less ambiguity, fewer duplicate tasks, and more time for the things we actually care about. And if the process of making these diagrams is a little more fun — that's even better.

We should be spending a lot more than 9% of our time on strategic work and major goals. The right diagramming methodology and tools can help us do what we love with less frustration and wasted effort. If you love the sound of that, then it's time to reconsider how you're making your diagrams.

Knut Sveidqvist is CTO of Mermaid Chart
Share this

Industry News

December 06, 2023

ngrok unveiled its JavaScript and Python SDKs, enabling developers to programmatically serve their applications and manage traffic by embedding ingress with a single line of code.

December 06, 2023

Data Theorem introduced API Attack Path Visualization capabilities for the protection of APIs and the software supply chain.

December 05, 2023

Security Journey announced support for WCAG, SCIM and continued compliance with SOC2 Type 2, which are leading industry standards.

December 05, 2023

Vercel announced a new suite of features for its Developer Experience (DX) Platform, made for enterprise teams with large codebases.

December 04, 2023

Atlassian Corporation has completed the acquisition of Loom, a video messaging platform that helps users communicate through instantly shareable videos.

December 04, 2023

Orca Security announced that the Orca Cloud Security Platform has achieved the Amazon Web Services (AWS) Built-in Competency.

November 30, 2023

Parasoft, a global leader in automated software testing solutions, today announced complete support for MISRA C++ 2023 with the upcoming release of Parasoft C/C++test 2023.2.

November 30, 2023

Solo.io achieved the Amazon Elastic Kubernetes Service (Amazon EKS) Ready designation from Amazon Web Services (AWS).

November 29, 2023

CircleCI implemented a gen2 GPU resource class, leveraging Amazon Elastic Compute Cloud (Amazon EC2) G5 instances, offering the latest generation of NVIDIA GPUs and new images tailored for artificial intelligence/machine learning (AI/ML) workflows.

November 29, 2023

XM Cyber announced new capabilities that provide complete and continuous visibility into risks and vulnerabilities in Kubernetes environments.

November 29, 2023

PerfectScale has achieved the Amazon Elastic Kubernetes Service (Amazon EKS) Ready designation from Amazon Web Services (AWS).

November 28, 2023

BMC announced two new product innovations, BMC AMI DevX Code Insights and BMC AMI zAdviser Enterprise.

November 28, 2023

Rafay Systems announced the availability of the Rafay Cloud Automation Platform — the evolution of its Kubernetes Operations Platform — to enable platform teams to deliver automation and self-service capabilities to developers, data scientists and other cloud users.

November 28, 2023

Bitrise is integrating with Amazon Web Services (AWS) to provide compliance-conscious companies with greater access to CI/CD capabilities for mobile app development.

November 28, 2023

Armory announced a new unified declarative deployment capability for AWS Lambda.