I’ve been porting all of my draw.io diagrams in Confluence to PlantUML. Both tools meet my minimum requirements for diagrams in documentation.
- The diagram must be editable inline in the document
- The diagram elements must be able to be links
- The diagram doesn’t need to look perfect, but it can’t be wrong.
It’s come down to Draw.io and PlantUML, which are very different from each other. Draw.io is a typical point-and-click drawing program. It’s web-based, and about as good as that can be. PlantUML is a programming language for creating diagrams. The editing experience is a text editor side-by-side with the rendered diagram. Both Draw.io and PlantUML can do my minimum list, but there are some things that are making me favor PlantUML.
- I’m documenting, not designing. I’m not trying to figure out the system I am documenting—I am just trying to communicate it quickly at the top of a document that goes into details. If I were still designing, I probably would want to draw, but honestly, it’d be on paper or with freeform drawing tools.
- I accept the default layout engine. In PlantUML, it’s best if you let the layout engine do it’s thing. I’m still learning how to influence it, but try not to worry about it too much.
- I’m comfortable with programming languages. PlantUML is a weird programming language with syntax affordances for diagramming and other embedded mini-languages. Simple diagrams are simple, but I find that I need the more advanced features for all of my diagrams.
- I like the idea of version control and diffing. It’s text, and line-oriented, so it works well with diffing.
- I could generate this. I love to generate code and so learning this will ultimately lead to me generating it some circumstances.
- I can edit quickly. If I want to fix a typo, I don’t have to click-click-click to get to the part where I can type. The text editor is very good. Also, I can easily copy and paste from other diagrams and samples.
- I can make my own library. Drawing tools let you make template shapes, but PlantUML is a programming language (with conditionals, loops, math, etc). The tools it has for abstraction are way beyond what drawing tools typically do.
I might just be repeating what the diagrams-as-code people have been saying all this time, but until PlantUML, I hadn’t used anything that was good enough to get these benefits (because they didn’t meet the minimum).