A colleague at work recently told me that I should check out PlantUML. His advice is usually good, and this is no exception.

PlantUML uses a relatively simple text language to describe the desired diagram, then makes generation of the image as simple as processing the UML file. It’s easy to try online at http://plantuml.com/ where there is a text editor with real time image updates as you add more content.

Sequence Diagrams

Sequence diagrams are probably the simplest to build, and are absurdly fast to create. Here’s a simple example of a TCP exchange:

To create this, I used the following PlantUML:

@startuml
title : TCP Exchange
HostA -> HostB : SYN
HostB -> HostA : SYN+ACK
HostA -> HostB : ACK
HostA -> HostB : Data
HostB -> HostA : ACK
HostB -> HostA : FIN
HostA -> HostB : ACK
HostA -> HostB : FIN
HostB -> HostA : ACK
@enduml

You’re not limited to two endpoints, of course:

Use Case Diagrams

Here’s a simple use case with Fred and Joe again:

The PlantUML to generate this was:

@startuml
title : Result of Gossip
Fred --> (HR) : complaint
(Legal) -> (HR) : advice
(HR) -> Joe : reprimand
note right of Joe : Unamused
@enduml

The use of --> as the arrow from Fred to HR makes the line vertical rather than horizontal. You can actually use -left->, -right->, -up-> and -down->, to explicitly select a direction. There isn’t fine control over placement of objects and lines, but using options like line direction and note positioning, it is possible to manipulate the appearance to some degree.

Activity Diagrams

Here’s an easy way to build those process flows you’re asked to create for ISO27001 and the like:

@startuml
partition Requestor lightblue {
(*) -right-> "Create Request"
--> "Send Request\nto Engineering"
}

partition Engineering lightgreen {
"Send Request\nto Engineering"  -right-> "Receive Request"

if "    Request\n     Complete?" then
  -->[yes] "Process\nRequest"
  -down-> "Mark As Complete"
  -right-> (*)
else
  ->[no] "Identify Gaps"
  -->[Return To\nRequestor] "Create Request"
endif
}
@enduml

This image, while demonstrating a few new features also shows how the inability to finely control the label “Request Complete?” means that we are at the mercy of the underlying GraphViz layout engine, which is not always perfect.

Other Types

PlantUML also offers other diagram types not shown here, including:

• Class diagram
• Component diagram
• State diagram
• Deployment diagram
• Object diagram
• Wireframe graphical interface (mock up UI)

Export

PlantUML can export to PNG, SVG and LaTeX formats, and for sequence diagrams –with some effort– you can generate an ASCII art version, so for those of you writing an RFC right now, this may make your life simpler.

Alternatively you could just use the online interactive tool and copy the resulting image from the web page.

My 2 Bits

This is a fun tool! Anybody who has used GraphViz before will be familiar with the agony of seeing an almost but not quite perfect diagram being generated, and as PlantUML uses GraphViz under the covers, you should expect the same here. That said, with a little effort (and occasionally some text padding), the results can be quite impressive for such a small outlay of effort. I’m particularly impressed at the ease with which a sequence diagram can be created; I’ll be using that in the future.

If you try it out, let me know what you think!