Using Plain Text Language to Draw Diagrams

Diagrams are great in conveying ideas especially when describing something that has multiple levels of abstraction. I've personally used whiteboards to describe ideas through basic shapes, sequence and class diagrams, and flow charts. Then if the diagrams need to be communicated electronically, I would translate them to either Visio, Lucidcharts, Draw.io, or Enterprise Architect before communicating to the intended recipients for feedback.

Building diagrams the first time is the easy part. The biggest challenge is in soliciting feedback from colleagues when there are changes to a diagram instead of a fresh new one. How does one know what changed especially in a class diagram, a sequence diagram, or even in a flow chart? Using Visio or other diagramming tools that use binary files is virtually impossible to review using comparison tools. This is the case as well when the file format is XML-based much like Draw.io. Sure it's text, but it's so verbose that it might as well have been binary.

Furthermore, how does one quickly provide feedback with only a few minutes to dedicate to it? In the past, I've personally printed the two versions of the diagram then looked at them against the light while on top of each other. Who has the time to do that?

These challenges have led us to build diagrams using plain text language. Using plan text language in creating diagrams is just like writing code. And since it is code, it can be managed, reviewed, and treated like code. Some of the benefits of it are as follows:

  • The changes are more apparent.
  • It fosters better collaboration between team members.
  • Code review activities apply in managing and reviewing diagrams.

Here's an example from http://plantuml.com/sequence-diagram

@startuml
Alice -> Bob: Authentication Request
alt successful case
    Bob -> Alice: Authentication Accepted    
else some kind of failure
    Bob -> Alice: Authentication Failure
    group My own label
        Alice -> Log : Log attack start
        loop 1000 times
            Alice -> Bob: DNS Attack
        end
        Alice -> Log : Log attack end
    end    
else Another type of failure
   Bob -> Alice: Please repeat   
end
@enduml

http://plantuml.com/sequence-diagram

The tool that we use to draw diagrams in plain text language is PlantUML. Some of the use cases are:

How do you keep them up to date? ...write the text (code) and use a viewer. Tools to use: PlantUML website for quick diagrams, and through IntelliJ IDEA, Eclipse, other IDEs.

How do you review changes in the diagrams? ...view the text (code) diff and use a viewer. Tools to use: Git diff, other diff tools

How do others review changes? ...view the text (code) diff and use a viewer locally or through your version control system. At GoHealth we use Bitbucket with git. Couple those with the PlantUML Chrome Extension, downloading the raw file displays the diagram for quick visual inspection. Since the diagram code is in text, we use Bitbucket's code review feature in pull requests to review and comment on changes. This applies to github, etc. as well.

How do non-technical team members review changes? At GoHealth we use Confluence. With the PlantUML Confluence plugin, we are able to embed the PlantUML code directly. Using Confluence's version diff feature, diagrams can be compared just like the rest of the document.

There are a few things to note before you decide to use PlantUML.

  • You give up some control of layout and flow. (It's probably a good thing.)
  • It is not a general purposes diagramming tool.

Lastly, I find drawing sequence diagrams using PlantUML very helpful in communicating system interactions especially with a large group of people. Using spoken words is a very inefficient way of communicating ideas to 25 or so people in a conference room and to those connected remotely. I usually find myself plugging my laptop to the conference room projector, sharing my screen, and drawing sequence diagrams using PlantUML in getting my point across. "Your system is on the left, my system is on the right, you call this, I return this, yada, yada, yada. Done."

Join Our Team

Explore engineering Opportunities at GoHealth