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

2024-12-11 Wednesday

Problem

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

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

2. 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 repetetion and lost effort.

3. Nature of tools: Most of the diagramming software are drag-and-drop interfaces. Although it feels intuitive at first, it often works against the diagram designer. The designer easily ends up mixing structural and visual problem spaces 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.

Local Rendering Installation (MacOS)

I use VSCode for all operations: writing, previewing and exporting. The plugin can be found from VSCode Marketplace. It's also possible to run PlantUML from command line as well.

# Java
brew install --cask temurin
# Graphviz
brew install graphviz

Usage

Author files with extension wsd. Use VSCode's command palette to run PlantUML or click preview from top right while you have the file open.

Examples (to be updated)

Here are some quick examples to get you started:

Example 1: Simple Sequence Diagram

@startuml example1
Alice -> Bob: Hello, Bob!
Bob --> Alice: Hi, Alice!
@enduml

Example 2: Basic Class Diagram

@startuml example2
class User {
    +name: String
    +email: String
    +login(): void
}

class Admin {
    +manageUsers(): void
}

User <|-- Admin
@enduml

Example 3: State Diagram

@startuml example3
[*] --> State1
State1 --> State2: Event
State2 --> [*]
@enduml