UMLBehaviour diagrams

How to draw a UML sequence diagram

One scenario, the participants it actually touches, the happy path in order, then the branches - and a hard stop at one screen.

August 5, 20267 min readUML 2.5.110 of 35

The short answer

Start with one scenario written as a sentence. If you cannot name the single run in one sentence, you have a use case, not a sequence diagram.
Place participants left to right in the order the flow first touches them, actor leftmost. Anything else guarantees crossing arrows.
Crossing arrows here are not a style problem - they make the reading order genuinely ambiguous, and the order is the whole point.
One screen, about fifteen messages. Past that the diagram is scrolled rather than read, and a ref fragment should carry the second half.

An early UML sequence diagram. A guest submits a booking request to a booking site, which asks an availability service whether a room is free and then writes a reservation to a store. Every message is answered. — After step three. One scenario, straight through - and already the ordering is settled.

01Steps one and two: one scenario, then its participants#

Write the scenario as a sentence before drawing anything. "A guest books a room that is available" is a scenario. "Booking" is not - it is a use case, which covers every run including the ones that fail, and a diagram that tries to be all of them is the diagram that ends up eighty messages long. If your sentence contains the word "or", you have two scenarios or one alt fragment, and you should decide which before continuing.

Then list the participants that scenario actually touches, and place them left to right in the order it reaches them. The actor goes leftmost. Four or five is the working range; if you have seven, at least two of them are implementation details that the flow does not reason about, and deleting them will not lose anything a reader needed.

02Step three: the happy path, in order, and nothing else#

Draw the run where everything works, top to bottom, with no fragments at all. That is the diagram in the hero above, and it is finished as a piece of work even though it is not finished as a diagram - the ordering is settled, which is the expensive part.

Two conventions carry most of the meaning. A message label is an operation with its arguments, not a description: isFree(dates, roomType) tells a reader what the receiver must offer, where "checks availability" tells them a story they already knew. And every reply is dashed - a solid arrow coming back is a second call, and it means something different.

Activation bars are optional in UML 2.5.1 and worth drawing. They are the only thing on the diagram that shows a synchronous call is blocking its caller for the whole nested exchange beneath it, which is usually the fact the diagram was drawn to establish.

03Steps four and five: the branches, and stopping#

The same UML sequence diagram after adding branches. The availability check is wrapped in an alt fragment: when the room is free the site reserves it and confirms; when it is not, the site asks for alternatives and offers them instead. A payment hold is fired asynchronously at an audit log. — The same flow after step four. The alt is wrapped around the point where the answer starts to matter.

Only now add the fragments, and add them one at a time, asking of each: does this branch change what the reader must build? A branch that returns an error and stops rarely does, and is better recorded in the use case text. A branch that does other work - like offering alternative dates above - always does, and belongs on the diagram.

Wrap the frame around the point where the paths diverge, not around the whole diagram. The alt above starts after the availability verdict comes back, because everything before that is common to both outcomes; a frame around all nine messages would be technically legal and would tell the reader nothing about where the decision is.

Then stop at one screen. This is not a soft guideline: a sequence diagram exists to make an order visible at a glance, and a diagram that has to be scrolled has given that up while keeping all of the cost. When a flow will not fit, split it at a natural seam, give each half a name, and reference the second from the first with a ref fragment - or draw an interaction overview diagram above the set.

In one line each

01Write the scenario as a sentence first. If it contains 'or', decide between two diagrams and one alt.
02Participants go left to right in the order the flow reaches them, actor first.
03Draw the happy path with no fragments. Labels are operations with arguments; every reply is dashed.
04Add a branch only if it changes what gets built, and wrap the frame at the point paths diverge.
05One screen. Past that, split and use a ref fragment.

Three finished flows to copy from: the worked examples.

04Common questions#

Where do I start when drawing a sequence diagram?

With one scenario written as a sentence, not with the boxes. A sequence diagram describes a single run through a flow, so if you cannot say which run in one sentence you do not yet have a diagram - you have a use case, and that is a different picture.

In what order should participants be placed?

Left to right in the order the flow first touches them, with the actor leftmost. Doing anything else guarantees crossing arrows, and crossing arrows on a sequence diagram are not a style problem: they make the reading order genuinely ambiguous.

How long can a sequence diagram be?

One screen, or about fifteen messages. Past that the diagram is no longer read top to bottom, it is scrolled, and the ordering that was the whole reason to draw it stops being visible. Split it and reference the second half with a ref fragment.

ShareX LinkedIn

↑ Back to top All UML articles →

In this series