Why Creating Diagrams is Hard (and How PlantUML/Mermaid Can Help)

2024-12-11 Wednesday (Updated on 2025-07-30 Thursday)

Problem

Creating diagrams is often a lot of work. While they are useful for conveying complex ideas visually, several issues make the process cumbersome:

• Iterations: Diagrams require multiple iterations to get right. Things change as ideas evolve and comments come in. These changes are often reflected in diagrams, and constant manual refinement is time-consuming.
• Structural vs. Visual Challenges: When creating diagrams, you’re solving two problems at once:
  • Ensuring the structure accurately represents the underlying concept.
  • Making the diagram visually clean and readable. Rearranging elements like boxes and arrows for alignment is required, but done multiple times it becomes a repetition and lost effort.
• Nature of tools: Most of the diagramming software are drag-and-drop interfaces. Although it might feel intuitive at first, it often works against the diagram designer. The designer easily ends up mixing structural and visual problems too early.

Solution

PlantUML is a simple and efficient way to create diagrams using relatively simple syntax. Instead of relying on drag-and-drop tools, PlantUML lets you define the structure of your diagrams and then automatically render them. This approach addresses many of the challenges:

• Focus on structure first, and let PlantUML handle the layout.
• Quick iterations by editing text instead of rearranging elements manually.
• Easy to version control with Git.

Another widely used option is Mermaid which has 1st party support e.g. in Webstorm.

On related note, I built an application called Selkie to help me with authoring Mermaid diagrams.

Bonus

I really like Gantt diagrams for planning. Here's one in PlantUML:

And here's how it looks like: