We’ve started to embrace PlantUML in our Systems and Software engineering teams at work.

One nice feature of this markup language is creating diagrams programmatically. We wrote a small python tool that will take a State Transition Table (States cross Events) and create the diagram. I have found it helpful to start from the table to ensure States and Events are well defined and all options are considered, but once that is done the diagram is also quite useful for discussion.

Things that we have found helpful are the MediaWiki plugin and the Word plugin.

We’ve also started adding unique identifiers to all diagrams across our large development program, and keeping all diagrams in one central spot. That alone has been almost as useful as PlantUML.