Hi all. I am Peng Xiao. I am the author of ZenUML – a textual UML tool that takes markup text (DSL) and converts it into sequence diagrams. It is an honor for me to showcase the product here. If you would like to integrate it into your applications, please see the end.

Why a new text to Sequence Diagrams tool?

The question I am often asked is: There is already PlantUML (and other tools) so why do you bother to build another one?. In fact, some guy on reddit even asked me to give up. Well, ZenUML at least is doing a better job in some cases. Read to see how they compare according to three dimensions: DSL, Feedback, Output.

The DSL to define sequence diagrams in ZenUML

I started using sequence diagrams heavily around 2006. Since then, I have tried quite a few tools, including PlantUML. I like the idea of generating diagrams from text because I hate to constantly drag-and-drop and double-click to edit names etc. One thing I am not quite happy with PlantUML is its DSL. IMHO, it quickly gets unreadable when you start nesting logic as you can see in the above video. So I had to find a better way for presenting nesting logic: ‘{}’. It is widely used in the mainstream programming languages (sorry Python).

The following sequence diagram shows how a RESTful API might be implemented. Please note the DSL at the left-side. I hope most developers find it familiar enough.

For a full language reference, please go to https://www.zenuml.com/help.html.

DSL comparison (PlantUML vs ZenUML)

For PlantUML users, I have prepared a table showing which features are implemented in ZenUML and the difference in the language. Note, ZenUML supports sequence diagram only (for now).

Feature PlantUML ZenUML Comment In PlantUML’s basic* syntax, occurrence (the execution bar) is not drawn. In ZenUML, the occurrence is a first class element. Every message comes with an occurrence which shows how long the execution takes. @startuml User->A:method @enduml A.method To send a message to self, just call a method without mentioning target participant. ZenUML does not allow self message to be the outermost message. This is because, in practice, we need a message from boundary (or an Actor) to ‘start’ the interaction. @startuml A->A:selfMessage @enduml A.method() { selfMessage() } This is where ZenUML really outperformed. PlantUML’s DSL becomes hard to read quickly as we add nesting relationship. In addition, if we change the order of ‘deactivate B’ and ‘deactivate A’, the diagram would remain the same, which is flawed. The ZenUML syntax is simple and consistent. Note that, in the highlighted line, we did not mention ‘A’. It was deduced from the context. @startuml participant User User->A:MethodA activate A A->B:MethodB activate B deactivate B deactivate A @enduml A.methodA() { B.methodB() } The two implementations look similar. Note that, in ZenUML, in the two highlighted lines, we did not mention ‘A’. It was deduced from the context. While in PlantUML, we actually can put ‘B->Log’ there, which will produce an invalid diagram (or one that is very unlikely to be the user’s intention). ‘Loop’ is very similar to ‘Alt’ in both implementations. @startuml User->A:MethodA alt successful // B->Log: Success A->Log: Success else A->Log: Failure end @enduml A.methodA() { if (successful) { Log.Success() } else { Log.Failure() } }

* PlantUML supports occurrence with ‘activate/deactivate’ keywords.

Without doubt, PlantUML is a great tool good and has features (and a huge ecosytem around) that ZenUML does not have. For ZenUML, two features are under development – ‘return’ and ‘new’ keywords; one is planned: Comments as notes.

However, what makes ZenUML unique is that it is an (opinionated) modelling tool. ZenUML enforces a valid model, while PlantUML allows you to draw anything. When there are more than two levels of nesting, PlantUML becomes hard to read, while ZenUML remains readable. For example, the following code, effectively, generates the same diagram:

@startuml participant User User -> A: MethodA activate A A -> B: MethodB activate B B -> C: MethodC activate C deactivate C deactivate B deactivate A @enduml A.methodA() { B.methodB() { C.methodC() } }

Output

While PlantUML produces diagrams as pictures (png, svg) and some other tools generate ASCII or draw on Canvas, ZenUML takes a different approach. It produces pure HTML DOM elements. The benefits are:

You can apply any styles on it – different colors, borders, fonts and even handwritten styles. You still can produce images from it. This is already supported in the Chrome Extension . It is searchable. Participant names, messages are all text on the page. If you insert the diagram into another document, it is indexable.

Feedback

PlantUML and most other tools have a ‘Submit’ (or ‘Refresh’) button. You have to click that button to get the resulting diagram. This is because they need to send the code to the backend server and get the picture back from the server. Websequencediagrams does not have the button, but it does a best-effort work to show the latest diagram. It is still far from being instant. As you can see in the GIF, ZenUML provides instant feedback to the user’s input. This is because all the conversion happens in the browser, no back-end request at all.

Js-sequence-diagram is implemented in a similar way. There is a difference though. With Js-sequence-diagram, the whole diagram is re-rendered every time you type in a letter. It is kind of distraction. ZenUML is implemented with VueJs. VueJs implements a Virtual DOM, and it only updates what you have changed (participant names, messages, etc.).

A little bit of history and more

The first version of this tool was created in 2010 as a work for the first HTML5/CSS/JS competition in ThoughtWorks China. It was first implemented with drawing diagrams on Canvas. That version is still on github.

The source code for the website and Chrome Extension is also hosted on github (site, extension). Feedback and/or pull request are welcome.

Integration and license

It is super easy to integrate it to any web-based applications. You can find a demo project on github. If you need help, please drop me a mail at eagle.xiao(at)gmail.com.

All the pseudo code and generated diagram (in its HTML format and/or image format) are owned by the author of their corresponding source code (that is, their textual description in ZenUML language).