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.

Most people meet UML the same way: somebody drops a diagram into a document or a channel and expects it to be understood. You do not need all fourteen notations to do that. You need five questions, asked in this order, and they work on a diagram kind you have never seen before.

1. What kind of diagram is this? Look at the top-left corner first. A well-drawn diagram carries a frame with a tag - sd for an interaction, act for an activity, stm for a state machine, cmp for components. If there is no tag, the shapes give it away: stick figures and ellipses are use cases, a vertical dashed line is a sequence diagram, rounded boxes with arrows are activity or state.
2. What is one box? This is the question that decides everything else. A rectangle can be a type, a single instance, a replaceable component, a machine, or a partition of responsibility, and the same drawing means five different things depending on the answer. An underlined name means an instance rather than a type - that one convention resolves the most common confusion on the spot.
3. Which end of each line is decorated? UML puts the meaning on the ends. A hollow triangle points at the more general thing, a diamond sits on the owning whole, an arrowhead points at what is used or called. Reading the mark and ignoring the direction is how a diagram gets remembered backwards.
4. What do the small labels say? Numbers like 0..* are multiplicities and describe the end they touch. Square brackets are guards - a condition under which that path is taken. Guillemets like «interface» say what kind of thing a box is. These three carry more information per character than anything else on the page.
5. What is it deliberately not saying? Every diagram kind is silent about most things, on purpose. A class diagram says nothing about order; a sequence diagram says nothing about duration; a component diagram says nothing about where anything runs. Half of all misread diagrams are somebody reading an answer out of a notation that cannot express the question.

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.

UML is one of about six notations an architect meets, and the question is almost never "is UML good" but "is UML the right one for this drawing". They overlap in shape and not in subject, which is why picking by habit goes wrong so quietly.

• BPMN - for processes people carry out.Same OMG, different subject. When the diagram is about who does what and in what order across departments, BPMN's pools and lanes say it far better than an activity diagram, and every process analyst in the building already reads it.
• ArchiMate - for the enterprise around the software. Capabilities, business services, applications and infrastructure in one language, deliberately coarser than UML. It is the right altitude for a portfolio and the wrong one for a class.
• SysML - for systems that are not only software. Started life as a UML profile, so the diagrams look familiar, and it adds requirements and parametric diagrams for engineering where hardware and physics are in scope. If your system has a mass and a power budget, this rather than UML.
• ER and crow's foot - for data as a database sees it. A class diagram and an ER diagram of the same domain look similar and are not the same claim: one is about types and behaviour, the other about tables and keys. The cardinality notation differs too, which is a reliable source of confusion in a review.
• C4 - for explaining a system to people quickly. Not a competitor so much as a way of organising diagrams into four zoom levels. It is deliberately loose about notation, and plenty of teams draw C4 levels using UML shapes.
• Mermaid and PlantUML - text that renders into diagrams. A syntax rather than a language: what they draw is mostly UML. They are excellent for a diagram that belongs in a pull request and weak where a real model is wanted, because there is no model underneath - only a picture regenerated each time.

The practical rule: choose by who has to read it. Engineers reading a design get UML. A process owner gets BPMN. An architecture board gets ArchiMate or C4. The same information drawn in the notation its audience already reads is worth more than a more precise diagram nobody opens.

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.