DEVOPSdigest

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