UML use case diagrams

A use case diagram is a map of scope. It names the people and systems that interact with what you are building, the goals they come to it with, and the line between inside and outside. That is all it does, and its restraint is the point.

It says nothing about order. Nothing about screens, fields, or algorithms. Nothing about how anything works. Every one of those is a different diagram, and the temptation to smuggle them onto this one is what produces the sprawling, useless use case diagrams that gave the notation a bad reputation.

Nobody hands you a list. The diagram above looks obvious once drawn and was not obvious at all beforehand, and the gap between a blank page and that picture is four questions you can ask in a room in twenty minutes.

1. Who starts something here?Every one of them is a candidate primary actor. Ask for the role rather than the name - the person who said "I do that" is one holder of a role that will outlast them.
2. Who or what receives something without asking? Reports, files, notifications, settlement runs. These are the supporting actors on the right-hand side of the boundary, and they are the half of the diagram most first drafts miss.
3. What has to be there for this to work? Payment providers, identity services, the mainframe, a fraud engine. Anything you would raise a ticket with another team about is outside the boundary and belongs on the diagram - drawing it is often the moment somebody realises the dependency was never agreed.
4. What happens because time passed? A nightly reconciliation, a fourteen-day expiry, a monthly invoice run. Time is an actor, drawn as a stick figure labelled Clock or Scheduler, and processes that leave it off end up with use cases nobody appears to start.

Then name each goal from the actor's side of the counter, verb first, in their vocabulary: Submit payment, not Payment submission handling and certainly not PaymentController. If the name only makes sense to somebody who has seen the code, it is a step in a use case rather than a use case.

These two are the reason use case diagrams get drawn wrong. Both are dashed arrows with a keyword, and they point in opposite directions.

«include» points from the base to the thing it always does. Read it as "calls". In the diagram above, Submit payment includes Authorize payment: you cannot submit without authorizing. It exists to factor out behaviour shared by several use cases - which is exactly why Refund payment includes it too.

«extend» points from the optional extra back to the base. Read it as "may interrupt". Log audit trail extends Refund payment: refunds work without it, and it happens under some condition. The base use case does not know its extensions exist.

The diagram is the table of contents. The thing that gets built from is the use case description behind each ellipse - and a project that draws the diagram and never writes the descriptions has produced a picture of work rather than a specification of it. This is the part the notation says nothing about, which is why so many teams stop at the picture.

There are three useful depths, and choosing one is a project decision rather than a modelling one. A brief description is two sentences in the backlog. A casual one is a paragraph per scenario. A fully dressed one has the fields below, and is worth the effort for the handful of use cases that carry real money or real risk.

• Name. The ellipse's label, verb first: Authorize payment.
• Primary actor. Whoever wants the result. Merchant.
• Stakeholders and interests. Who else cares and what they need out of it. The acquirer wants a valid authorization code; the fraud team wants the attempt recorded whether it succeeds or not. This field is where most missed requirements turn up.
• Preconditions. What is already true before the use case starts - the merchant is authenticated, the order exists. Not a list of steps, a list of guarantees.
• Main success scenario. The numbered happy path, actor step then system step, in the language of the business. Somewhere between five and twelve steps; more than that and the use case is really two.
• Extensions. Numbered against the step they branch from - 4a, 4b, 7a - each with its condition and what happens. This is the field that actually earns the format, because it is a systematic prompt for every way the happy path fails.
• Postconditions.What is true afterwards, on success and on each failure. "An authorization is recorded and the funds are held" is testable in a way that "the payment is processed" is not.

Worked small, for Authorize payment: the main success scenario is (1) the merchant submits the payment, (2) the system validates the order total, (3) the system requests authorization from the acquirer, (4) the acquirer returns an approval, (5) the system records the hold and confirms. The extensions are where the work is - 3a the acquirer times out, 4a the acquirer declines, 4b the acquirer requests a step-up challenge - and each of those is a conversation somebody would otherwise have had six weeks later in a defect triage.

A useful use case diagram fits on one page and has somewhere between three and ten ellipses. It is a table of contents, not the book. The detail belongs in use case descriptions - the numbered main flow and its alternatives - or, if the flow is branchy enough to be worth drawing, in an activity diagram per use case.

1. Functional decomposition. Twenty ellipses named after buttons. Use cases are goals; if it is not something an actor wants, it does not belong.
2. Actors named after people or job titles in your org chart. Model the role. One person can be several actors, and one actor can be a batch job.
3. «include» and «extend» arrows reversed. They point opposite ways. Apply the removal test above.
4. Actors inside the boundary. The boundary is what you are building. An actor is by definition outside it.
5. Sequencing implied by vertical position. A use case diagram has no time axis. Nothing about the layout says what happens first.