UML Diagrams the Simple Way

There is a great engineering aphorism to “Keep It Simple Stupid!”, the KISS principle.

Many developers often confuse easy and simple; I’ve done it in the past, and will probably again in the future. Where you stand can a big difference to your perspective.

Take UML Diagrams and particularly drawing and collaborating with them. There are dozens of editors out there that allow you to easily drag/drop/link etc. all your different diagrams and classes. They’ll remember relationships and properties and other funky things. This can make it very easy to draw a diagram, or many diagrams. Unfortunately it can also make life everything other than simple for those you need to collaborate with, updating the diagrams when you lose the tool (e.g. out of business, or license expired) or you don’t have the tool, or it doesn’t run on your computer.

One reason I’m a big fan of the TodoTxt format (and even have my own TodoTxtJs tool) is that it makes life very simple. It’s not the easiest tool to work with, it’s not always easy to do every task, but it is an extremely simple format, and the big advantage of that is compatibility and portability. I don’t need anything more than Notepad to read and manage my Todos, and there’s no way I’ll ever not be able to edit or read them. Tools can make me more productive, but I don’t need them.

Wouldn’t it be great if the same applied to UML diagrams? Interestingly it does. Enter plantUML.

Take this example definition:

Even if you’d never seen the diagram and never seen the syntax before, using a bit of effort, and some knowledge of UML, you’d be able to figure out what it’s describing. That is one aspect of what makes this simple.

In case you’re curious, this is the actual sequence diagram, and that’s just one of the many formats it understands:

UML Sequence Diagram


It also makes it a really elegant solution for collaborating with people. You don’t need to send huge binary files around in proprietary formats, just send simple text. You don’t even need the same “compiler” or “renderer”. Just knowing the syntax you could write your own, just as you’re able to understand what it’s showing by reading the text. A more complex diagram might require a paper and pencil 🙂

It also means that if you need to render it in a different way (e.g. colours, shapes, style) just use a different renderer. You have, coincidentally, gone a long way to separate content from presentation, and that’s almost always a good thing.

As an added bonus, if you’re storing your designs and documentation in a source control system, then you can diff a text file much more easily than complex binary file.

The good news is that plantUML is open-source and free, so there’s no likelihood of it ever going away, although it does have some dependencies (GraphViz and Java) but those are also open-source. There are loads of ways to use it, even from within your IDE. My only disappointment is that there’s no VisualStudio plugin yet.

Of course, it’s much easier to drag & drop stuff with a mouse and have lots of funky tools do things for you auto-magically. Where those “easy” tools fall down is that you need to get the software, make sure it works and runs on your set-up, have it available and understand how to use it and, most importantly, that everyone else does too. What makes this text based syntax simple is that anyone can just open the file and work with it using any text editor.

If you can ensure that everyone you will ever work with, and have to collaborate with, will have the same tools; you have the tools and infrastructure to collaborate easily using that tool and you’re sure you’ll keep access to those tools for the entire life of your project/product, then using the “easy” tools might be your best choice.

If you cannot ensure that, then you’re probably much better off looking for a simpler solution like plantUML.





Share on Google+0Share on Facebook0Digg thisShare on Reddit0Share on StumbleUpon0Share on Tumblr0Tweet about this on TwitterPin on Pinterest0Share on LinkedIn0Email this to someone

Leave a Reply