A logistics platform's engineers cannot explain what happens when a delivery is attempted and fails. What communication artefact would help most?
Show the full answer Hide the answer
The artefact
A sequence diagram of the failure path, not the happy path. The success case is usually understood and usually simple. The value is in the exception flow — failed delivery attempt, reattempt scheduling, customer notification, return initiation, payment reversal, seller notification — which crosses many systems, involves external parties, and is where nobody can reconstruct the behaviour from the code without hours of work.
Why this specific artefact
- It shows ordering and timing, which structural diagrams cannot. The question "what happens when the notification is sent before the payment reversal completes" is answerable only from a sequence.
- It shows the external participants — the carrier, the customer's phone, the seller's system — which is where the actual complexity lives.
- It makes the ambiguous states visible: the window where a delivery is marked failed and the reversal has not yet completed, which is exactly the state a support agent will be asked about.
- It is stable. A failure flow changes far less often than the code implementing it, so the maintenance cost is low relative to the value.
What to draw and what to skip
Draw the two or three flows that are genuinely difficult and skip everything else. A sequence diagram of a simple read is waste; one of a compensating transaction across four parties is the most valuable page in the documentation set.
A diagram earns its maintenance cost when it explains something hard to derive from source. Structure is easy to derive; cross-system interaction under failure is not.
The operational payoff
In a physical-world domain the same diagram serves three audiences: engineers designing changes, support agents explaining a situation to a customer, and operations staff deciding whether to intervene manually.
That third audience is usually forgotten and is the one that most needs it, because they are making real-time decisions about physical goods based on a system state they must interpret correctly.