The Problem

You hold an architectural idea in your head, but are struggling to communicate it. Team members think differently about what things are called, where they live, and how they tie together. Someone erased the whiteboard (and what was there was impossible to read a few days later anyway). You’ve seen diagramming used in other places, but you don’t want to install some crappy tool with an impossible user interface (and what do all those symbols mean anyway?!).

If you’re in this situation, I’d encourage you to take a look at UML (Unified Modeling Language). It’s recently become a useful tool in my belt, with a combination of the following enablers:

• Plant UML - a free REST API that will generate pretty images from a UML document
• Postman - an indispensable ecosystem for invoking and testing http APIs
• Paint.Net - a free Windows app that’s light years better than MSFT Paint

With these 3 in combination, I can quickly produce UML diagrams that describe in a single picture what laborious conversations (voice and text) cannot:

UML

As with any new language, UML may look a little confusing at first. Don’t be dismayed, it’s very simple, especially for “quick and dirty” use cases (which is typically how I use it). In general, you’ll be adding the following:

Start tag:

@start uml

Define your groups and participants:

box "Picture" #LightGreen
	participant OnePicture
end box

box "Word" #LightBlue
	participant ThousandWords
end box

Define interactions between participants:

OnePicture -> ThousandWords : "Are we equal?"
ThousandWords -> OnePicture : "Yes."

And don't forget your end uml tag:

@enduml

This simple example above produces the “Picture is Worth a Thousand Words” diagram above!

Plant UML

Plant UML is a handy service that will generate SVG images from UML diagrams. Additionally, they have fantastic documentation that provides both high-level overviews of UML features, as well as details when you’re ready to get into the nitty gritty. This is a valuable resource for scaling the UML learning curve. Here’s the URL we will use to generate the diagrams:

POST http://plantuml-service.herokuapp.com/svg

Postman

Postman should require no introduction if you’ve developed web-based APIs (REST, SOAP, etc). If you haven’t used it, I highly recommend checking it out - it is an irreplaceable part of my development toolbox. In addition to the downloadable tool, their subscription service adds team sharing, documentation, testing components that we at EarthClassMail use extensively.

In order to generate UML, we need to do two things:

1. Fill the POST URL (http://plantuml-service.herokuapp.com/svg) in the Postman input
2. Paste our UML in the body:

The UML above results in the following easy-to-read diagram:

Getting the Output

The last step involves getting your UML diagram out of Postman and into an image file, and I’ll admit, it’s a little hoaky. There are a couple different ways of accomplishing this. Both involve the use of the wonderful Paint.Net for actually saving the output.

Poor Man's

If your diagram is small enough (ie, fits entirely in the Postman output window), then a simple approach is to take a screenshot (Ctrl-Alt-PrtScn), paste into Paint.Net, crop accordingly, and save. Easy Peasy.

More Involved

If your UML diagram exceeds the output pane dimensions within Postman, fear not, the following (slighly convoluted) steps will allow you to save the full output.

1. In Postman, there is a down arrow on the “Send” button. Click it, and select “Send and Download”. This will cause Postman to save the results in an SVG file (that’s the format PlantUML returns).
2. Now for the weird part - converting the SVG to something Paint.Net will recognize (in this case, a PNG file). I use the handy SVGtoPNG website to accomplish this. There may be better ways - this works for me :)
3. Once you have your PNG, you can open in Paint.Net, crop/trim/highlight/annotate, and away you go!

UML-ing the Night Away

Hopefully this short tutorial has inspired you with the confidence to embark upon a fantastic UML voyage. No longer will you be held captive by the shortcomings of human language! Let the machines lead you to technical communication nirvana!