Getting Started with PlantUML: Why It Belongs in Your Toolbox

This is the inaugural post on puml.online, drafted with AI assistance. It serves as a content sample — feel free to borrow its structure, tone, and pacing when you write your own pieces.

What is PlantUML

PlantUML is a tool that draws diagrams from plain text descriptions. You write a code-like markup and the PlantUML engine renders it as a UML diagram (PNG, SVG, PDF, you name it).

1
2
3
4

@startuml
Alice -> Bob: Hello
Bob --> Alice: Got it
@enduml

That snippet renders a simple sequence diagram.

What can it draw

With a few extra config lines you can also produce ER diagrams, JSON trees, YAML trees, mind maps, network topologies, and a dozen other types.

Why use PlantUML

• Version-controlled: diagrams are text — git diff works, they fit into code review
• Reusable: templated, sharable across the team
• Automatable: run plantuml in CI, regenerate architecture diagrams on every release
• Cross-platform: written in Java, runs nearly everywhere; a WebAssembly build also runs entirely in the browser
• Rich ecosystem: plugins for VSCode, IntelliJ, Confluence, GitLab, GitHub

How to get started

Three quick ways:

1. Online: plantuml.com/plantuml — open and use
2. VSCode plugin: search “PlantUML”, install, write .puml files with live preview
3. Local CLI: requires Java 11+, then plantuml diagram.puml produces PNG/SVG

How it compares

• draw.io / Visio: drag-and-drop, prettier output, but no diff, painful to maintain on large projects
• Mermaid: similar syntax, pure JS, natively supported on GitHub/GitLab; supports fewer diagram types
• Structurizr DSL: C4-model specific, more structured, but steeper learning curve

My take: Mermaid is fine for everyday diagrams; PlantUML wins for architecture, complex sequence diagrams, and state machines.

In the next post I’ll share 5 copy-paste-ready templates for the most common diagram types.