What is UML?

UML is a visual language for describing software systems. It gives you a fixed set of shapes, lines and rules so that a diagram you draw means the same thing to somebody who did not sit in the room where it was drawn.

That is the whole value proposition, and it is worth being blunt about it. A box with a name in it is not UML. A box with three compartments, a hollow triangle pointing at another box, and a 1..* at one end of a line is UML, and it says something precise: this type inherits from that one, and one instance of the first is associated with at least one of the second. Anyone who knows the notation reads that identically. That is what you are buying.

The language is maintained by the Object Management Group. The current release is UML 2.5.1, published in 2017. It descends from the work Grady Booch, James Rumbaugh and Ivar Jacobson merged at Rational in the mid-nineties, when the field had roughly fifty competing notations and no way to read anyone else's design. OMG adopted UML 1.1 in 1997. Version 2.5 was largely a cleanup: the spec had split into "infrastructure" and "superstructure" volumes that few people could navigate, and 2.5 folded them back into one document.

Every UML diagram answers one of two questions. Structure diagramsanswer "what is this system made of?" - the parts, the types, the machines, and how they are arranged. They describe things that are true regardless of time.

Behaviour diagramsanswer "what does this system do?" - the flows, the messages, the states, and the order things happen in. They describe things that are only true at a moment.

A class diagram tells you a Payment has an amount and a status. A state machine tells you a payment goes from Authorized to Captured but never the other way round. Neither can express the other, and most real questions need one of each. If you find yourself trying to show sequence on a class diagram, that is the signal to draw a second diagram rather than to overload the first.

Behaviour has one extra level of nesting. Four of the seven behaviour diagrams - sequence, communication, timing and interaction overview - are all interaction diagrams, four different renderings of the same underlying idea: participants exchanging messages. They are interchangeable in principle. In practice sequence diagrams dominate because a vertical time axis is the easiest thing in the world to read.

Here is the entire language, at the level of "do I need this today?". Follow a link when the answer is yes.

In practice a healthy majority of real-world UML is four of these: class, sequence, use case and activity. The other ten exist because somebody needed them, and three or four of them are genuinely excellent when the situation calls for it - a state machine for a lifecycle, a deployment diagram for an infrastructure review. The rest you can read when you meet them and never draw.

Start from the question, not from the diagram. The mistake is picking a diagram type first and then deciding what to put on it - that is how you end up with a class diagram of two hundred boxes that nobody has ever read.

• "Who uses this and what for?" - use case diagram. Scope and actors, before any design exists.
• "What are the concepts and how do they relate?" - class diagram. The default structural view.
• "What happens when someone clicks pay?" - sequence diagram. Order of messages between participants.
• "What is the process, including the branches?" - activity diagram. Flow with decisions and parallelism.
• "What states can this thing be in?" - state machine diagram. Lifecycle and legal transitions.
• "What runs where?" - deployment diagram. Nodes, artifacts, environments.
• "What are the services and their contracts?" - component diagram. Provided and required interfaces.
• "How is the codebase organised?" - package diagram. Grouping and allowed dependencies.

It is not a process. UML says nothing about when to model, how much to model, or who signs it off. It is a notation. Methods like RUP were built around it and are frequently confused with it; you can use UML on any process, including none.

It is not a programming language. UML models can be detailed enough to generate code, and some tools do exactly that. Most teams do not, and should not. Complete round-trip code generation is the single most common reason UML efforts collapse: the model becomes a second, worse copy of the source that nobody updates.

It is not all-or-nothing. There is no requirement to use all fourteen diagrams, or to model every class. Drawing one sequence diagram to settle an argument about who calls whom is a completely legitimate use of UML, and probably its most valuable one.

It is not the same as ArchiMate. Both are modelling languages and they overlap enough to be confusing. UML models software - classes, components, messages. ArchiMate models the enterprise around it - business processes, capabilities, application and technology layers. A large organisation typically needs both, at different altitudes.

The honest answer is: much less than the tooling encourages. A model earns its place when it is read more often than it is edited. Three things reliably produce that.

Model the parts that are hard to hold in your head. The payment state machine with nine states and two illegal transitions is worth a diagram. The three-field DTO is not.

Model at one altitude per diagram. The most common failure in a real class diagram is mixing domain concepts with framework plumbing on the same canvas. Two diagrams, each internally consistent, beat one that is technically complete.

Model what you will keep. A diagram in a slide deck is a drawing with a shelf life of one meeting, and that is fine as long as you know that is what it is. A diagram in the repository, next to the code it describes, is a model - and it needs an owner.

If you are new to the notation, read the class diagramarticle first. It carries the largest share of UML's vocabulary - generalization, association, multiplicity, composition - and every other structure diagram reuses those marks. Then read the sequence diagram article, which does the same job for behaviour.

Those two cover most of what you will ever be asked to read. Everything else in this series is written to be picked up on the day you need it, in any order, and each article assumes only those two.