I am not sure how many people care about this anymore but UML still is a very effective way to communicate with other developers when the architecture is complex enough. Particularly when it comes to sequences of events that need to be described, one sequence diagram seems to make a big difference.
Recently, I was writing a document regarding a particular architecture that needed several class diagrams/sequence diagrams et al. I started out using “Enterprise architect” which is okay but it is way too heavy weight and it comes with a lots of bells and whistles. To top it, at the end of it all, it generates crapload of stuff that dont contribute materially to my actual documentation of the architecture. And, It needed me to have windows box around to put that together. The next option was running visio or OmniGraffle but for both of them, it was way too much work to make the sequences to appear exactly the way I wanted it to show up.
So, I started looking for tools and I came across PlantUML. Between PlantUML and GraphViz, I can now do everything I want staying within vim. I prefer using text based tools to generate images since it is easier to keep it up to date and archive and edit with Vim. And PlantUML, is perfect for that.
It generates sequence diagrams without anything else and since it is a java application, it actually works on a mac like a charm. If you want to generate class diagrams and others, you need to install Graphviz. Note that on Mountain Lion, I had to install libtool before I could successfully run it but it was well worth it.
In PlantUML, it is extremely easy to create sequence diagram.
@startuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response @enduml
generates this image.
And it has so many plugins, It is amazing.
Syntax is simple enough and the documentation on the site is very easy to follow. Now, I can do my documentation within Vim between markdown and PlantUML/GraphViz.
I am one happy architect..