I recently discussed my diagramming style with an author of a book in my signature series. The question arose as to whether I was using UML or some other standard or style. I hadn’t given that much formal reflection, but when the question was posed, I did gather some thoughts around my style. Thinking about it more I realized that, for the past 12-15 years or so, my diagrams have been used to communicate architecture ideas and options without strictly adhering to any specific diagramming standard.
As a side note, I have seen some readers of my books make remarks about my use of UML. The comments are generally negative. I think that’s because UML has largely fallen out of favor since it is often seen as a heavyweight modeling language. Although UML can be heavyweight, I think that in general throwing all uses of UML under the bus is arbitrary and closed-minded. This is especially so since my use of UML is quite limited and lightweight, as you will see in this post.
I will continue with some brief explanations and examples based on this: Although my architecture diagrams and those that I use to express designs before, during, or after writing code, are influenced by UML, they are also different from UML. The point is that I diagram to communicate, not to comply.
Most of the following diagrams and illustrations are from our book, Strategic Monoliths and Microservices.
The Blend
After at least a decade using UML, I formed my own diagramming style that blended UML with some elements that had even looser rules. This was necessary to include business stakeholders in design conversations. UML was becoming less important and most business people would be lost with more than some boxes and lines along with some sequence numbers to show processing steps. My style’s basic syntax was more dynamic in nature than the simpler parts of UML (e.g. class diagrams). UML has both static and dynamic diagram types. The most popular dynamic diagram type is Sequence Diagrams. Yet, I didn’t like the formality required by those. (See the below End Note: UML Had Its Day for some history.)
And then came EventStorming.
In 2013 after my red book was published and I was on my IDDD Tour in Europe (a series of very low-cost IDDD Workshop events), EventStorming was introduced during my Belgium workshop. (I tell more of this history in the book Strategic Monoliths and Microservices.) At that point I started including EventStorming in all of my IDDD Workshop events and in design work. This lead to the idea that I should represent all of my diagram elements as possible using the colors of EventStorming sticky notes. Figure 1 gives you an idea of what I mean.
Figure 1 is an illustration from our book. It shows the typical elements used during EventStorming sessions. The colors have specific meanings. I provide icons to help those who have partial and full colorblindness. The icons can be easily drawn in the upper left or right corner of the sticky note, which leaves plenty of room for the name of the element.
When using UML, typically all class types would be represented by one color; let’s say pale yellow. To distinguish one kind of class, such as an entity, from another class, such as an event, you’d use a text-based stereotype name that displayed above the class name in various diagrams. Examples of the stereotype labels are <<entity>> and <<event>> and the like. You can imagine having to place a stereotype name, such as for all the types in Figure 2, in all class/object types. Some UML tools support using icons in place of the stereotype names. But I have, to my recollection, never seen stereotypes as icons in UML tool usage. Even if icons are used, colors are missing, so color doesn’t play a role in making each of the element types jump out at you.
Figure 2 shows you how EventStorming colors work when modeling in time order.
Figure 2, from our book, provides a cheat sheet for EventStorming. Of course the book explains these uses in detail, and there are many more uses than summarized in these mini segments. The uses of various elements and intensities of any one of them will depend on the modeling contexts, such as big-picture and design-level storming.
Now, putting this all together, the following Figures 3a and 3b provide a few diagrams that show dynamic processes, or sagas, in my diagramming style.
Note the use of sequence numbers in both diagrams in Figure 3a and Figure 3b. These are a throwback to UML where I blend Object and Collaboration Diagrams. As I said, I don’t like the constraints of using UML Sequence Diagrams. For one thing, updating Sequence Diagrams is usually a pain because with most tools you end up moving invocations and returns with values across all object lifelines. You can’t just insert a new invocation line and have the tool make room for it by adjusting the positions of now later interactions. The style that I use is a bit easier to deal with when adding more detail. But then again, the examples used in our book are the results of employing drawing tools.
Kalele is building the modeling tool Domo. It hosts seven model types, including EventStorming, DDD Context Maps that are auto-derived from EventStorming models, Topo Architecture (a blend of EventStorming results with Context Maps), Mind Maps, Impact Maps, Specification by Example (BDD), and User Stories. You can collaborate with team members live using shared models on virtual whiteboards. Currently registration and use is free of charge with no limitations. You can expect support for other model types in the future. Click here to register today.
I tend to like the second diagram in Figure 3b over the one in Figure 3a. It even appears that there are less steps. However, the cleaner diagram is due to the compromise of dropping the Message Bus element from Figure 3b. Figure 3a was drawn specifically to show how the use of a Message Bus fits into the orchestration. So the compromise in Figure 3b isn’t good for the complete communication of the architecture. I know, because I first tried to draw using the Figure 3b approach, but with the Message Bus the lines got really messy.
So, what’s the best drawing layout? As always, it depends.
What’s the Situation?
The way that I draw a diagram depends on this situation, and the situation is generally a matter of the media type rather than the problem at hand. The media, such as a book, a paper or specification (document such as PDF), or a slide deck, definitely impacts my presentation. Generally books support wide rather than tall diagrams, as do papers and specifications. So there is an emphasis on taking advantage of width, and that definitely constrains the style. It’s similar with slide presentations, but the resolution is far more limited than a book-hosted diagram. In this case, I might require a summary diagram that I show first followed by slides that zoom in on specific areas shown in the summary. Examples are shown as facsimiles in Figure 4.
The best diagramming situation is when I can use a modeling tool or even a basic drawing tool with virtually no limitations and that I can screen share and even invite participants to my diagramming session. You can see the range in Figure 4. Figures 3a shows those for books and spec/docs. Figure 3b gives an example of unlimited, but which is actually constrained by the fixed size of the image itself.
Optimizing for Width Over Height
When diagram height is at a premium but width is more on your side, optimize for width. In Figure 4, notice that the book and spec/doc are basically the same. The spec/doc using Letter or A4 page sizes will have more room than a book, but it’s still limited. The purple (wide element at the bottom) represents a Saga or Process Manager as you see in Figure 3a.
You can see the contrast by comparing the unlimited diagram to the far right. There, the saga is represented by a purple circle at the center of the diagram. There is plenty of width and height to draw the flow with different elements and in more detail.
Showing More Detail
There are times when a diagram requires more detail. Even when modeling with EventStorming I find the need to sometimes show details on some elements, such as entities, events, and views. For example, there might be a significant entity attribute/property to remember. The same goes for events. And you might want to show some important aspects of query model view documents. When this is needed, I find that using UML class element compartments is very handy. See Figure 5 for an example.
Although Figure 5 shows limited examples, you can certainly include attributes/properties and even important methods/functions using UML class element compartments. There, was that so bad? Remember, it’s all about communication. Don’t let arbitrary prejudice against UML make communication less effective.
End Note: UML Had Its Day
I started using UML around the time that Martin Fowler’s UML Distilled was published. Some years ago I asked Martin if he considered UML more a formal language for precision modeling or one used for communication. He said definitely the latter—communication—and that UML Distilled was written with that mindset. That’s a starting point for the discussion about a blended style.
I still have my original copy of UML Distilled from 1997, and it still contains the flash cards that I created to help me memorize the modeling language. I’ve included a few of the cards in photos, as you can see in Figures 6 and 7.
The front side of each card shown in Figure 6 is a hand drawing of a UML diagram type. The flip side shown in Figure 7 has a summary of the syntax used in various parts of the diagram. Some have abstract diagrams that only reflect diagram element names, while others have examples of business and technology that I was working on and with at the time. For example, note the Microsoft MFC based on Document and View; namely Document, DocView with a SplitterView, and MainFrame (which has nothing to do with big iron). The MFC was a condensed MVC framework where the Document is the Model and the View and Controller are combined in DocView. That is similar to what Digitalk offered with its Smalltalk/V.
I did learn how to be very precise with UML, knowing all the rules for just about every diagram type. Even so, I didn’t learn that from UML Distilled. There was just enough syntax detail in Martin’s book to make UML make sense to software engineers, and I suppose business people alike, for communicating software architectures and designs. Yet, the business stakeholders in my world never used UML.
The few times that I participated in some sort of UML training workshop, it was more about preciseness than higher-level communication. Those were in the late 1990s and early 2000s, and based on Model-Driven Architecture (MDA) and Model-Driven Development (MDD). I was hopeful that these paradigms would lead to something substantial because I have long sought ways to be precise and render bug-free implementations. However, I found that very few companies succeeded with MDA and MDD.
Later, I would still use UML for architecture documents, but I didn’t attempt to be as precise as I was capable. The industry was far from done with UML so I didn’t get any backlash. In fact, my documents were adored by technical management. Still, UML eventually had its day and it was time to move on.
