Diagrams from Text with PlantUML

Visual models are an important tool for analysts because they provide another way to look at and think about the topic at hand. Written documentation is good and necessary, but the written word is subject to interpretation and misinterpretation. Visual models and diagrams provide another way to communicate and interpret critical information. Examples of visual models include process flows, entity-relationship diagrams, wireframes, and use case diagrams. Maps and timelines also help us visualize information. During meetings, I often sketch diagrams on a whiteboard or with a pen and notepad. It's a great way to summarize information and check your alignment. Digital diagrams are often easier to read, maintain, and share.

There are many tools available to help you create diagrams. Most of these give you a drag-and-drop interface that lets you visually place and manipulate objects in the diagram. While this type of interface promises to make diagramming quick and painless, there are downsides. Manipulating objects visually can take a lot of time, especially as the size and complexity of the diagram increases. Making changes to a diagram often requires you to tear your diagram apart and then put it back together after you've added, changed, or removed elements. It can also be a challenge to allow others to make and share changes to a diagram you've created. After a while, it may be easier to throw it all out and start over! The ease-of-use promised by the WYSIWYG interface fades quickly.

PlantUML is a tool that lets you create diagrams from text. This can be a real advantage over WYSIWYG interfaces for a few key reasons. Working this way can be faster because there is no searching for, placing, sizing, and manipulating visual elements. Any text editor can be used to write PlantUML code. Text can be easily modified, shared, and version controlled. The syntax used by PlantUML provides yet another way to think about the idea being represented in the diagram – by considering each element on its own, we can give each one our full attention. When you are done making changes to your PlantUML text file, you use the PlantUML software to render your diagram. PlantUML can be downloaded and run locally, or you can use the web-based service at PlantUML.com.

I'll admit that there are times when PlantUML isn't the best choice. The diagrams it generates are not the most beautiful things I've ever seen. For wireframes, especially, I would go back to using something like LucidChart. PlantUML also has limitations around the size of its diagrams. It's possible to divide images up into multiple pages but, for very large and complex diagrams, other solutions, like Visio, might be preferable. For low to medium complexity diagrams, PlantUML is an interesting tool that lets you create diagrams without pixel-pushing, and it makes updating and sharing diagrams easier than performing surgery with a mouse.