Visualizing Ideas and Designs with Diagram-as-Code Tools

The Power of Visual Communication

As a systems architect and innovator, I've learned that visual communication is one of the most powerful tools in our arsenal, at least for people who are not visually impaired. Whether we're designing software architectures, outlining workflows, or documenting processes, diagrams play a crucial role in helping us to communicate complex ideas clearly and effectively. Diagrams help us to convey complex ideas, clarify requirements, and align our teams. But traditional diagramming tools (i.e., Visio, Lucidchart) often fall short when it comes to collaboration and version control. This is where diagram-as-code tools shine, and today, I'll share my journey with two of my favorites: PlantUML and Mermaid.

My Journey with PlantUML

My first contact with code-as-diagram tools was in fact with DOT (more than 10 years ago), a language for creating graphs. I used it to create a few diagrams in Notepad and then compile them with Graphviz. It was a bit cumbersome, but it worked. Then I discovered PlantUML, which is a more powerful and flexible tool for creating diagrams using plain text. PlantUML supports a wide range of diagram types, including sequence diagrams, class diagrams, activity diagrams, and more. It's a versatile tool that integrates seamlessly with popular editors like VS Code (which I use daily with extensions: PlantUML, Markdown All in One, and Markdown PDF), enabling real-time visualization of diagrams as you type, and export to various formats (PNG, SVG, PDF, HTML, etc.).

Image Source: VS Code PlantUML Extension

When I first discovered PlantUML, it was like finding the perfect hammer for a stubborn nail. I needed a way to visually explain ideas and designs directly from my code editor. PlantUML allowed me to create detailed diagrams using plain text. It integrates seamlessly with VS Code, enabling me to see the resulting diagram in real time as I type. This immediate feedback loop is a game-changer.

For example, when designing a new microservice architecture, I can write out the components and their interactions in PlantUML's simple syntax. Here's a snippet of what that might look like:

@startuml
actor User
User -> WebServer: Request
WebServer -> ApplicationServer: Process Request
ApplicationServer -> Database: Query
Database --> ApplicationServer: Result
ApplicationServer --> WebServer: Response
WebServer --> User: Response
@enduml

With PlantUML, this text quickly transforms into a sequence diagram, providing a clear, visual representation of the flow. The ability to export these diagrams as images, PDFs, or HTML means I can easily share them in presentations, documentation, or reports.

Why Mermaid Complements PlantUML

While PlantUML covers a broad range of diagrams, there are times when I need something more specialized or when I am working within a specific documentation framework. This is where Mermaid comes in handy. Mermaid uses a markdown-like syntax to generate diagrams, and it's directly supported by Docusaurus, a popular documentation framework.

For instance, when I am documenting a project using Docusaurus, I can embed Mermaid diagrams directly within the markdown files. This is particularly useful for creating flowcharts, Gantt charts, Gitgraph Diagrams are amazing, and more. Here's an example of a simple Gantt in Mermaid:

gantt
    title La Rebelion Tasks
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2024-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2024-01-12, 12d
        another task    :24d

Mermaid's syntax is intuitive and easy to learn, making it a perfect complement to PlantUML. The ability to integrate directly into documentation ensures that my diagrams are always up-to-date and easily accessible.

Real-World Applications

Using PlantUML and Mermaid together has transformed how I document and share complex ideas. Whether I am presenting a high-level system architecture to stakeholders or outlining detailed workflows for my development team, these tools help me to create clear, precise, and engaging diagrams.

One particularly memorable project involved designing a multi-cluster Kubernetes architecture. Using PlantUML, I was able to create detailed component diagrams that illustrated the relationships between various services, pods, and namespaces. These diagrams were instrumental in aligning the development team and ensuring that everyone had a shared understanding of the architecture. These diagrams made it easy for everyone, from developers to DevOps engineers, to visualize the different components and their interactions on each different cluster.

With Mermaid, I was able to create the Gitgraph diagrams that showed the evolution of the project over time. This was particularly useful when explaining the branching strategy and release process to new team members. The ability to embed these diagrams directly into our documentation made it easy for everyone to access and understand the project's history, even more, because several teams were working on different products and services at different paces.

When it came time to document the system, Mermaid played a crucial role. Embedding flowcharts and Gantt charts directly into our Docusaurus-based documentation ensured that the entire team had access to up-to-date, detailed visuals of our workflows and timelines. This not only improved our documentation quality but also enhanced our team's efficiency and collaboration.

Beyond PlantUML and Mermaid

So far we have seen how PlantUML and Mermaid can be powerful tools for creating diagrams using plain text. These tools have become indispensable in my workflow, enabling me to create, share, and maintain high-quality diagrams effortlessly. But they are not the only tools available. Let's explore other diagram-as-code tools that I don't use but are worth mentioning along with the Domain Specific Languages (DSLs) they use:

Graphviz

• DSL: DOT language

• Description: Graphviz uses the DOT language to describe the nodes and edges of graphs. It's widely used for creating complex network diagrams and hierarchical layouts.

Diagrams

• DSL: Python

• Description: Diagrams is a Python library that simplifies the creation of cloud architecture diagrams. It supports AWS, Azure, GCP, and other cloud providers.

Structurizr

• DSL: Structurizr DSL, C4 model

• Description: Structurizr provides a great way to document and communicate software architecture. For "coding", it uses C4 Model diagrams using a text-based DSL or programmatically through Java, .NET, and other languages.

Kroki

• DSL: Multiple DSLs (supports PlantUML, Graphviz, Mermaid, and more)

• Description: Kroki integrates various diagramming tools under a single API. It supports multiple diagram languages, making it a versatile choice.

Asciidoctor Diagram

• DSL: Multiple DSLs (supports PlantUML, Graphviz, Mermaid, and more)

• Description: Asciidoctor Diagram is an extension for the Asciidoctor toolchain, enabling the inclusion of diagrams in AsciiDoc documents using various DSLs.

Each of these tools offers unique features and capabilities, making them suitable for different use cases. Whether you're creating cloud architecture diagrams, software architecture diagrams, or network diagrams, there's a diagram-as-code tool that can help you visualize your ideas effectively.

Comparative Analysis

Here's a comparative table summarizing the key aspects of each diagram-as-code tool and its DSL:

Integrating Diagram-as-Code Tools into Your Workflow

If you're new to diagram-as-code tools, here are some tips for integrating them into your workflow:

1. Start Small: Begin by creating simple diagrams using PlantUML or Mermaid. Experiment with different diagram types and syntaxes to get a feel for how they work.

2. Integrate with Your Editor: Install the PlantUML and Mermaid extensions for your code editor (e.g., VS Code) to visualize diagrams in real-time as you type.

3. Leverage Templates: Use existing templates and examples to create complex diagrams more efficiently. Both PlantUML and Mermaid have extensive documentation and examples to help you get started.

4. Collaborate and Share: Export your diagrams as images, PDFs, or HTML to share them with your team, stakeholders, or clients. Use version control to track changes and updates. With technical collaborators, you can use Git to track changes and collaborate on diagrams.

5. Automate Documentation: Embed PlantUML and Mermaid diagrams directly into your documentation using Docusaurus, Asciidoctor, or other documentation frameworks. This ensures that your diagrams are always up-to-date and accessible to your team.

By following these steps, you can quickly incorporate diagram-as-code tools into your workflow and start creating high-quality diagrams with ease. Whether you're designing software architectures, documenting workflows, or visualizing complex ideas, PlantUML, Mermaid, and other diagram-as-code tools can help you communicate more effectively and drive better project outcomes. 🚀

Conclusion

To become a successful systems architect or technical leader, clear communication is key and you need to master the art of visual communication. Diagram-as-code tools like PlantUML and Mermaid offer a powerful way to create detailed, high-quality diagrams using plain text. These tools enable you to visualize complex ideas, workflows, and architectures with ease, enhancing your ability to communicate effectively with your team, stakeholders, and clients. By integrating these tools into your workflow, you can improve collaboration, streamline your documentation process, and ultimately drive better project outcomes. 🙌🏼

If you haven't explored diagram-as-code tools, please try PlantUML and Mermaid. Their simplicity, flexibility, and powerful integrations might just revolutionize the way you work, as they have for me. 🤓

Any other diagram-as-code tools you'd like to recommend? Share your thoughts in the comments below!

For more insights on diagramming and other state-of-the-art tools in software development, stay tuned to my blog and newsletter. Let's continue to innovate and improve together. Go Rebels! ✊🏼🦄