Understanding Diagrams as Code From Idea to Implementation

What is Diagrams as Code?

Diagrams as code is an approach to diagramming that requires you to represent the way a diagram should look as a code artifact. Rather than creating the representation of your ideas in a visual form, you define the way the diagram should look in text form — it’s a similar idea to the way you would write code that represents a web page.

It’s a simplified way — hands on keyboard rather than drawing shapes — to conceive what a diagram is going to look like.

For a deep dive into diagrams as code and how it helps teams tackle technical documentation, check out our webinar on this topic. Along with exploring the benefits of and implementation methods for diagrams as code, we also discuss how Gliffy is investing in this idea to better serve technical teams.

However, if you don’t have time to watch the thirty-minute webinar, keep reading for an overview of the highlights!

Key Benefits of Embracing Diagrams as Code

Why would you want to use diagrams as code — isn’t it easy enough to draw the boxes and lines that form a diagram on your own? 

It’s Faster and Easier

Adept coders might prefer writing diagrams as code because it’s faster for them to communicate their ideas in that way. Being able to visually convey information is a powerful skill that may not come naturally to all technical professionals — but there is still great value in visuals when it comes to communicating the high-level design of something, so diagrams as code fills that gap by providing a way of visually conveying information using the language that’s more intuitive to technical teams.

It Allows You to Focus on Content

The idea of diagrams as code is born of the same ethos as most other “___ as code” movements, such as infrastructure as code, where you take a concept that is not usually depicted as code and turn it into code. 

This has the natural effect of allowing the diagram creator to focus on the actual information and letting a tool handle the responsibility of making that information look the way it should look, with proper spacing, alignment, and so on.

Being able to focus solely on the content of the diagram and letting a different tool take your input to create the actual picture for you also contributes to a faster and more efficient diagramming experience. When you don’t have to worry about colors, line weight, text sizes, and all the other visual aspects of a diagram, you’ll be able to generate the content you need to create the visual without distractions. 

It Helps You Align Your Workflows

Treating diagrams as code artifacts helps you integrate them more efficiently with existing processes and tools. For example, if you wrote a simple representation of an entity-relationship diagram, you can quickly edit the text, search and replace, and make other changes much easier than you could with an image file or a diagram you created by dragging and dropping shapes onto a canvas. This makes it easier to align your diagrams with version control, code review processes, and other workflows.

Diagrams as code also contributes to a culture of collaboration and knowledge sharing. If you build diagrams in a way that is easy for people to read and collaborate or comment on as part of their existing workflows, they’re more likely to take that opportunity. 

It Creates a Consistent Language Across Teams

Choosing a specific framework for your diagrams as code efforts makes it easier for individuals across teams to understand the structure and purpose of your diagram. It also makes it easy for them to reproduce it and view it as an image. This leads to more effective collaboration, especially for cross-functional teams.

Popular Frameworks for Diagrams as Code

The general concept of diagrams as code has been adopted by several different tools and methodologies that attempt to make diagramming faster and easier for technical teams. Here are a few of the most common frameworks for diagrams as code and the traits that define them. 

Graphviz

Graphviz is one of the older frameworks for diagrams as code, and one could argue that it’s the most battle-tested due to that wealth of experience. Graphviz is primarily used for flowcharts and weighted diagrams with lots of configurability. 

PlantUML

PlantUML is more focused on the domain of user stories and UML modeling, so the layouts it generates are closely aligned to those types of diagrams. 

Mermaid

Mermaid is a bit newer than the other diagrams as code frameworks, and what it attempts to do is split the difference between the first two solutions listed here, taking what it feels is the most popular subset of functionality from the other tools and streamlining it. This allows users to write the least amount of code to get the widest variety of potential results.

Mermaid is the framework that Gliffy users can utilize to create diagrams as code directly in Confluence Cloud today!

How to Implement Diagrams as Code

Here’s how to get started and set your organization up for success when implementing diagrams as code as your source of truth. 

Pick a Standard Notation and Align on Tools 

What tools does your team regularly use? Choose a framework for diagrams as code that integrates with your team’s regular workflows.

You can keep your diagrams as code in a directory somewhere, but if your team needs to search hard to find them or it requires lots of extra steps to turn that code into an actual image, that just adds back the friction that you were trying to remove in the first place by implementing diagrams as code.

The whole purpose of this practice is to collaborate and share information, so choose a tool that is harmonious with the way your team already works.

Start Small

Add just a little bit of diagramming to an artifact that didn’t have anything before. Starting somewhere, even if it’s only a few simple lines of code, is better than having nothing, and it’s a foundation for a new practice. Once you get started, you can begin to expand your diagrams, create templates, and encourage users to reuse common elements. 

Set Clear Expectations

It can actually be helpful to create documentation on how to create documentation — we know that sounds a little redundant, but all this means is that it’s important to give clear instructions and guidelines on when or where you would expect diagrams as code to be used. Setting clear expectations and answering questions is the best way to establish consistency and enable easy collaboration.

The Future of Diagrams as Code

We’re currently in the infancy of a broader movement of entering text into an AI tool to create the output of an image, and this idea is only going to get more prevalent — and more advanced.

Diagrams as code is a specific implementation of this idea, but we see the growing presence of many AI tools where anyone can input a description to receive an image that fits that description — with varying levels of accuracy, of course.

It’s likely that we will see tools like these continue to grow and more advanced tools developed to generate images, including diagrams, from text.

Create Diagrams From Code in Confluence

Gliffy offers the ability to create diagrams from code in the form of its Mermaid editor for Confluence Cloud. Try it today to create UML diagrams, entity-relationship diagrams, and more alongside your team’s documentation for a frictionless, collaborative approach to technical diagramming that your team will actually want to use.

TRY GLIFFY