A multi-step order flow with compensations is described in prose and nobody agrees on the behaviour. What does a sequence diagram add, and what must it show?

What it adds

Ordering and interaction made unambiguous. Prose describing "the order service reserves inventory, then charges payment, then requests fulfilment" leaves open what is synchronous, what happens concurrently, who waits for whom, and what occurs when a step fails. Those ambiguities are where the disagreements live.

A sequence diagram forces each of them to be decided, which is why drawing one frequently surfaces disagreements the prose concealed.

What it must show for a saga

1. The failure paths, not just the happy path. This is the whole point and the most common omission. A sequence diagram showing only success is a picture of the case nobody is arguing about.

2. Compensations as forward actions. A refund is not the absence of a charge; it is a new business action with its own state and its own customer communication. The diagram should show payment_refunded as a distinct outcome rather than an arrow going backwards.

3. Timeouts on every wait. Each point where one participant awaits another needs a duration and a defined action on expiry. A wait state with no timeout produces orders stuck forever, and the diagram is where that omission becomes visible.

4. Synchronous versus asynchronous, distinguished notationally with a legend. This is the single most important distinction in such a diagram and it is frequently left implicit.

5. Who owns the state. Which participant knows the current status of the order. If no participant does, the diagram has just demonstrated why nobody can answer "why is this stuck".

The conversation it produces

Drawing it typically reveals that inventory reservation must be strongly consistent and immediate — because overselling cannot be compensated — while payment, order creation and fulfilment can be asynchronous with compensation.

That asymmetry is the central design insight of the flow, and it emerges from asking "what happens if this step fails" at every arrow. The diagram's value is the questions it forces, more than the picture it produces.

The practical limits

A sequence diagram covering more than a handful of participants and a dozen interactions becomes unreadable. For a complex flow, several diagrams — the happy path, and one per significant failure mode — communicate far better than one exhaustive one.