What is Unified Modeling Language?

I consider Unified Modeling Language (UML) an overlooked diamond these days.

If you are not familiar with UML, it is a modeling language with a well-defined set of diagrams. These diagrams have been defined to help system and software developers specify, visualize and document software systems. In addition, there are also diagrams to aid business modeling. A modeling standard like UML is an essential tool to facilitate discussion and communication on current and future software development with least possible friction and assumption. It is great for the engineering part of software engineering.

There are two reasons why I find UML and overlooked diamond: I have realized that many junior developers don’t know much about the importance software modeling and and the existence of UML, coming out of university. This is both a shame and interesting at the same time. But even people who I think should know and would pursue modeling activities, mid-level and senior developers or architects, tend to keep visual modeling with a framework like UML to a minimum – and when they do it might be with a home brewed notation that is not easily understood by the receiver.

There could be many reasons for the lack of interest in UML. UML is not new and it’s definitely not part of the cutting edge that attracts most people. Also, UML may not be considered the most pleasing to the eye at first glance by some. Here’s an example of a minimal UML Use case diagram for a Point-of-sales system:

A UML Use Case diagram’s somewhat archaic look (source)

Furthermore, it’s a huge framework which I think is a discouraging factor – and therefore it can be hard to know when you know enough to use UML properly.

Not a fan, then a fan

Personally, I haven’t always been a fan of UML. I used it for quite some time, not because I really wanted to, but because it was the only option where I worked.
However, years ago I decided that I had to either discard the use of UML or really embrace it to get the most out of it. I chose the latter. I spent half a year studying UML intensely and discovered possibilities for modeling in detail, I had no idea was possible with UML. I’ve been a (pragmatic) proponent ever since.

I’ve used UML in some variation since 1999. When I worked on a large government project 6 years ago, we used Use Case and class diagrams. As recently as two years ago I assisted a spirits producer, let us call them Totally Rum, in a new digital transformation project, and our requirements modeling included a Use Case diagram, and activity diagrams (process), and both were central to visualize the system to stakeholders long before any code was written.

You can spice up your Use Case diagram…

When gathering requirements for new goals, outcomes, features and interactions in a new or existing system, at some point you’ll need to concretely discuss who will be able to do what in a given system or service. Use Case diagrams are great to achieve an overview of system interactions quickly and serve as a tangible foundation for an informed discussion early in the process. This. Is. Extremely. Valuable.

Use Case diagrams are great to achieve an overview of system interactions quickly and serve as a tangible foundation for an informed discussion early in the process.

Also, to work with UML does not mean you have to adopt everything defined by UML. You can cherry pick the best parts for your context. However, working with a well-defined framework means that you don’t have to discuss the plumbing of the notation – it’s ready for you to use as a common language. Using UML diagrams can be as simple as a hand drawn diagram, but will also keep up with your ambitions and complexity. This is also very valuable.

Introducing UML

I was advising a very promising young professional a few days ago. In his company they are in the early stages of discussing and defining The Next Big Strategic Feature. They were discussing several things at the same time:

  • What the users are supposed to do (major features are often composed of several small ones. This would also entail change to existing features, changing either their meaning or scope)
  • The physical composition of the existing system and the new addition (separate microservice or not, etc.)
  • The logical modeling (domain concepts, boundaries, user roles, processes)

For the first point, I suggested looking into UML Use Case diagrams. With permission I have reproduced parts of our conversation here:

Christer: Use Case diagram examples: https://www.uml-diagrams.org/use-case-diagrams-examples.html (I’d probably start here. Go to the section Examples of system Use Case diagrams)

AP: thank you!

CØ: Admittedly, not the most sexy look. But UML can really be your friend (it’s a very well established standard, and you can essentially model most if not all interactions and flows in a system, if you needed to).
An upgrade would be have this in mind while diving into Domain-Driven Design and thereby have the best of both worlds… (it’s a winning strategy in my book)

AP: 👌🏻I’ll try to do some to see how it goes


AP: in terms of planning, I totally still want to move forward with the Use Case diagrams. the only problem here is that I don’t feel we have a good understanding of the use cases right now and we’ll have to dig deeper, too many details. what do you think?

CØ: I think you answered the question yourself by saying, “I don’t feel we have a good understanding of the use cases right now and we’ll have to dig deeper”
This is why you’d want to start with a Use Case diagram early. You can even scope it to be “only” for the New Feature addition, including all new features and existing that are to be changed (to mean something else, to have a different result, to do something else etc.)
I’m 110% sure that a diagram, not matter how minimal and how wrong in the first iterations, it will help you weed out misunderstandings. I’ll happily help facilitate this process.

AP: Ok, but imagine the uml use case example of the airport check in process (the one you sent me). Would I be able do draw something remotely useful if I was never in an airport before and just knew that you needed to catch a plain?
Or you mean more in the sense: start with what you think you know and dig deeper into each uncertain part so you can understand it better and iterate with the diagram? That would make sense.

AP brought up an extremely important and interesting question here about the correctness of the modeling. In this case, the purpose of the modeling is to understand what the end result should be in the future, which puts modeling in the stage of carving out the goal and requirements gathering.
Of course we want to achieve some degree of correctness (high or “good enough”) of the diagram before we start coding, but it’s absolutely not necessary in the first iterations.

CØ: So, the Use Case diagram itself doesn’t include any strict process mapping, so in essence it could be what you know at this point (let’s say Check in, Add extra bag etc.)
So in that sense, for now, I think definitely it could be a good first diagram and discussion point.
Think of it as a first shared model, that you can have a conversation around – “OK, what do you, [business stakeholder], think Checking in entails? And you, [developer]?

No matter how little you think you know about the domain or how many assumptions you have in the beginning of a project, you’ll most likely always be able to assume something correctly. Strive to move the process forward even if it means that you will be wrong more than right in the beginning, and use it to bring the assumptions to light!

No matter how little you think you know about the domain or how many assumptions you have in the beginning of a project, you’ll most likely always be able to assume something correctly.

This is the most important point of using a modeling language: enhance understanding, weed out assumptions, share a mental model!

CØ: I send you this snippet of a template Use Case digram I made 5 years ago (when making a general description of Event-Driven Architecture). Colors and diagram look terrible, really, but that’s because I only had access to MS Visio at the time. This is for your inspiration. It doesn’t give away the meaning and rules behind the diagram, but consider having a discussion on a diagram like this with Filipe and Joāo, carving out the kinks with zero code made yet. I think that’s optimal, because changes are virtually free (for good and worse)

We did follow up, when I asked for permission to publish our conversation:

AP: About UML, I wanted to give a proper answer to what you wrote before, but I didn’t have the peace of mind. Fortunately, your article answered the questions I was going to ask. 🙂

CØ: What were your questions?

AP: what if I know that there is a check-in but don’t know what’s a check-in yet? would it make sense?
but as you said, I guess it still makes sense, it’s also a tool to organize ideas and build from there
and even as an exercise to start to learn it and put it in practice

CØ: Yes, then you are on a one-liner level of knowledge, so to say, place in the diagram and can carve it out from there

In conclusion

UML aside, start modeling early!

Modeling for the future is really about communication and discussion. Here, we narrowed down on modeling user behavior with a system and why a UML Use Case diagram may be what you need.

UML aside, start modeling early! Preferably yesterday. As validated with many of my peers, too many discussions about features, systems, processes start out without any visual aid and stay in this state for way too long. Without a model the discussion with stakeholders will be like this:

A few points on modeling a Use Case diagram:

  • The best response you can get from a customer is of course “You get the gist of what I want!” The second best answer is “That’s not what I mean”.
    In the requirements phase a Use Case diagram represents a view on a new future, with new or changed features. It is so much cheaper to be wrong in this phase and just alter the diagram than changing code or architecture later.
  • UML Use Case diagrams aren’t meant to stand alone. They should be part of an overall customer journey mapping or process mapping in an activity diagram.
  • Don’t strive for a 100% correctness when modeling for the future.
    The model should be correct enough for you to continue the work with as few assumptions as possible (80/20 rule applies). Use it to weed out assumptions. Be ready to change the model if the reality of the project changes.
  • If you are documenting, then strive for correctness.
  • Today, most people use User Stories. However, you can still use Use Case diagrams with the same purpose of achieving overview and discussion. They’re not mutually exclusive if you take a pragmatic approach.
  • A colleague gave me a good reason not to like UML: it has been heavily intertwined with visual designer tools for code generation. I have never seen UML based code generation tools work well in practice and can very much understand why that would deter people from adopting UML.