This content originally appeared on HackerNoon and was authored by Nick Angelou
When should you use No/Low Code, a DSL, or Code for creating diagrams?
🗺 The Landscape of Diagramming tools
When it comes to building and visualizing complex workflows, many software developers reach for tools like Graphviz. Of course, there are plenty of options, each with strengths in different diagram types and intended audiences. Some tools offer no/low-code interfaces for whiteboarding, others rely on their own DSLs, and a few even allow for programmatic diagram generation. But how does a software developer decide which one to pick?
\ The phrase “diagrams as code” is often associated with creating diagrams using DSLs, but what about generating diagrams directly from a programming language? Personally, I think this captures the essence of what “diagrams as code” should mean, as there isn’t a better term that truly differentiates it from DSL-based diagramming — but I digress. Here, I’ll use the phrase to refer to code-based diagram generation.
\ In this article, I won’t dive into detailed tool reviews. Instead, I’ll focus on when to use a no-code UI, a DSL, or a code-first approach, and why. I’ll mention some popular tools before getting into the meat 🍖 and potatoes 🥔 of each option. By the end, you’ll have a clearer idea of the tooling available in each category and what to take away from each approach.
Diagrams via No/Low Code
Here are a few tools that offer the ability to manage diagrams within an application without code. I don’t list all of them, but it should represent the class of tools that are available:
- Eraser.io — Deliver accurate, consistent designs faster
- Dalus — Modeling complex systems
- FlowCraft — A diagramming tool using AI
- LucidChart — Diagram your people, processes, and systems
- Whimsical —Designed to keep product teams aligned
- Microsoft Visio — Diagramming and vector graphics
- yEd — Diagramming Everywhere, Anytime
- … and many others
🍖 What Are No/Low Code Diagram Tools Good For?
No/Low-Code tools are designed to enable fast, flexible, and highly collaborative diagramming, without needing any programming or DSL knowledge. They focus on usability and accessibility, making it easy for anyone in the organization to create, edit, and maintain diagrams.
Here’s why No/Low Code tools can be useful for developers and engineering teams:
\
- Quickly create a diagram without setting up any tooling
- Allows for cross-functional accessibility to teams outside of engineering
- Often offer collaboration features in real-time
- Lowest learning curve
- They typically integrate across multiple platforms
\ Another benefit is ease of access — tools like Eraser allow users to generate clean, professional-looking diagrams that are easy to share across multiple platforms, improving accessibility for all.
🥔 When Should I Use a No/Low-Code Tool for Diagrams?
These tools are ideal for quickly creating collaborative visuals when the following criteria align with your project needs:
- ✅ You need to quickly create and update diagrams without a complex setup
- ✅ You need non-technical or cross-functional teams to view or edit diagrams
- ✅ You want collaborative, real-time editing and feedback
- ✅ You (or others) prefer not to learn a new DSL or code-based syntax
- ✅ You’re okay with limited customization in exchange for simplicity
- ✅ You’re okay with relatively small to medium-sized diagrams (< ~100 elements)
\ While these tools may lack the depth or customization of DSL or code-based options, they’re perfect for creating clear, collaborative visuals that get the job done without added complexity.
Diagrams via a DSL
I’ve put together another brief list to highlight some popular tools that offer ways to build diagrams using a particular syntax or DSL:
- Graphviz — The mature tool for generating diagrams via its own DOT DSL
- Terrastruct — A developer tool for Software Architecture diagrams via its own D2 language
- Mermaid.js — Creating many different types of diagrams using its own markdown-inspired DSL
- Eraser.io — Listed again, but also offers a way to use its own DSL
- Structurizr — Software architecture models using its own DSL
- Kroki — Creates diagrams from textual descriptions, supporting many DSLs with a unified API
- … and many others
🍖 What Are Diagram DSLs Good For?
DSLs are primarily designed with human readability and productivity in mind, making them ideal for capturing complex tasks in a given domain in a way that is both understandable and efficient.
\ Here’s why DSL tools can be useful for developers and engineering teams:
- They offer a simple, structured syntax that’s easy to learn and understand
- They make it intuitive to create diagrams without needing a general-purpose language like Python or JavaScript
- They’re ideal for cases where diagrams need to be updated infrequently
- They help teams capture essential structures quickly and consistently without the overhead of complex code
\ DSLs make the process of defining and visualizing graphs easier and more intuitive, without requiring in-depth knowledge of the underlying tooling. For example, the popular DOT language in Graphviz lets us clearly see relationships with just a few lines of code:
\
digraph {
A -> B;
A -> C;
B -> D;
C -> D;
}
\ We can easily make sense of the four nodes and their connections without knowing the underlying specifics. In addition, the simplicity of being able to modify a document and automatically produce a diagram allows technical teams to iterate quickly, especially when diagrams are created and updated only a handful of times each year.
🥔 When Should I Use a DSL for Diagrams?
Using a DSL works well when you need to create diagrams manually (in text or through a web canvas) for small to medium-sized visuals that don’t require frequent updates after the initial setup. Nowadays, you can have AI assist in generating the required syntax — neat!
\ You’re likely okay with the following:
- ✅ You want some control over layout and element relationships
- ✅ You want to create diagrams offline
- ✅ You’re fine with small-to-medium diagrams (< ~50 elements)
- ✅ You’re willing to invest more effort as the diagram grows
- ✅ You’re okay if the diagram isn’t always perfectly accurate
- ✅ You don’t mind copy-pasting elements (no modularity)
\ This may sound like a lot of trade-offs, but in practice, many diagrams you’ll want to create are straightforward and focused, without too much complexity.
Diagrams as Code
While many tools focus on DSLs or no-code options for diagrams, a few are designed specifically for a code-first approach:
- Vizdom — A Rust-based Diagrams as code tool for TypeScript (and soon more)
- Diagrams — Diagrams as code for Python (uses Graphviz under the hood)
- Go Diagrams — Same as Diagrams above, but ported to Golang
- Cytoscape — A graph theory (network) library for visualization and analysis
- Sigma.js — A JavaScript library aimed at visualizing graphs of thousands of nodes and edges
- NetworkX — A Python package for the creation, manipulation, and study of the structure, dynamics, and functions of complex networks
- D3-dag — A JavaScript library for visualizing directed acyclic graphs
- … and others
\ ==Note: Other DSL-first tools offer a programmatic API to generate diagrams such as Terrastruct and the many Graphviz wrappers.==
🍖 What Are Diagrams as Code Good For?
Diagrams-as-code tools allow developers to build and manage diagrams directly within a programming language, bringing code-driven flexibility and automation to the diagramming process.
\ Here’s why Diagrams-as-Code tools can be useful for developers and engineering teams:
- They allow diagrams to update automatically based on code or data changes
- They keep diagrams consistent by managing them within the codebase
- They’re perfect for cases where diagrams need frequent or daily updates
- They provide programmatic control over layout, styling, and relationships between elements
- They make it possible to reuse and modularize diagram components, reducing redundancy as diagrams grow
- They integrate easily with CI/CD pipelines, scripts, and automated workflows, enabling dynamic updates
🥔 When Should I Use Diagrams as Code?
Diagrams-as-Code tools are ideal when you need visualizations that stay in sync with code, evolve with the project, and integrate seamlessly into development workflows.
\ You’re likely okay with the following:
- ✅ You need to reflect the current state of your application or data
- ✅ You update a diagram multiple times per day
- ✅ You need integration within scripts, CI/CD pipelines, or automated workflows
- ✅ You want programmatic control over layout, style, and relationships between elements
- ✅ You need reusable and modular diagram components, reducing redundancy as diagrams grow
Conclusion
In the end, choosing between no-code tools, DSLs, and code-driven diagramming really comes down to your team’s needs and how often your diagrams change. No-code tools are great for quick, accessible collaboration; DSLs give you structure and simplicity; and code-first tools bring the flexibility to keep diagrams tightly integrated with your codebase.
\ Knowing the strengths of each lets you pick the right approach for your projects, helping you build diagrams that keep up with your work. With the right tool, you’ll spend less time tweaking visuals and more time focusing on what matters.
\ ==*A note on large graphs==
==Why do so few tools support large diagrams or graphs? For starters, diagrams with over 100 nodes and edges become hard to read, but they’re still important when visualizing tasks that can’t be otherwise understood — especially in cases of directed graphs like a program’s call graph.==
\ ==In general, diagrams with many relationships tend to require specific layout algorithms to reveal clusters and relationships rather than individual nodes. Great tools like Graphistry and Graphviz support this kind of visualization, making them go-to options for large, complex graphs.==
\
This content originally appeared on HackerNoon and was authored by Nick Angelou
Nick Angelou | Sciencx (2024-10-29T22:42:09+00:00) Diagramming Tools: When Should You Use No Code, DSL, or Code?. Retrieved from https://www.scien.cx/2024/10/29/diagramming-tools-when-should-you-use-no-code-dsl-or-code/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.