A use case diagram is a UML behavioral diagram that answers two questions: who interacts with the product, and what goals those people (or systems) have. It is not a flowchart and it is not a screen map. Each oval is a goal written as a verb phrase, such as Place order or Reset password. Each stick figure is an actor: a role outside the software.

Teams use use case diagrams at the start of a project because they are cheap to draw and easy to challenge in a workshop. Product managers can see missing actors. Engineers can see a goal that has no owner. Testers can later turn each use case into scenarios. If you need the steps inside a use case, switch to an activity diagram. If you need message timing, use a sequence diagram.

The diagram lives next to a short written description for each oval: trigger, preconditions, main success scenario, and a few failures. The picture is the index. The text is the contract. Do not try to put every sentence on the picture.

You can copy the PlantUML at the end of this article into the free UML diagram tool and adjust names to match your product. A gallery example shows a shop-sized starter.

An actor is a role, not a job title on an org chart. Customer, Admin, Payment gateway, and Inventory service can all be actors if they sit outside the system you are drawing. Primary actors start a use case. Secondary actors are invoked by the system (a payment provider is a common secondary actor).

The system boundary is a rectangle around the use cases that belong to this product. Anything outside the rectangle is not your code. That single box prevents a common error: mixing two products on one diagram. If you are drawing a mobile app and a warehouse system, you probably need two diagrams, or you need to treat the warehouse as an actor of the app.

Name the rectangle with the product name, not a vague word like System. Readers should know whether they are looking at Checkout, Admin console, or the whole shop.

Keep actor names stable across documents. If the written spec says Member and the diagram says User, reviewers will argue about identity instead of behavior. Align the words with your class diagram later, but do not draw classes on the use case view.

Write goals from the actor's point of view: Place order, not ProcessOrderForm. Avoid UI widgets (Click submit). Avoid internal jobs (Write to Kafka). Those belong in sequence or activity diagrams.

A good test: a stakeholder who has never seen UML should still understand the oval. If they ask which screen it is, the name is too technical. If they ask which department owns it, the name may be too broad.

Granularity matters. Login is often too small unless security is the subject of the review. Run the company is too large. Aim for a goal that can have a main success path of a few minutes of user time, or a single system-to-system transaction.

Group related ovals visually. PlantUML will place them; you can still use packages or comments to keep Browse catalog near Place order. Do not create twenty ovals that are all CRUD of the same noun. Merge them into Manage catalog if the workshop is about scope, and split later when you design APIs.

A solid line from actor to use case means that actor participates. You do not need arrows for simple associations. Multiplicity is rarely worth drawing on a use case diagram.

Include means one use case always uses another. Authenticate is a typical included case if every checkout path requires a session. Draw include as a dashed arrow with the stereotype include, from the base use case to the included one. Use include when the shared steps are a real goal that several ovals need, not when you are just factoring a function for programmers.

Extend means optional or exceptional behavior. Apply coupon might extend Place order. The dashed arrow goes from the extension to the base, with extend. Extensions need an extension point in the written spec (when the user has a code). If every order must apply a coupon, it is not an extension.

Generalization of actors (Admin as a kind of User) is legal UML and often noisy. Prefer two actors and shared use cases unless the hierarchy is central to access control.

If the diagram looks like a spider web of include and extend, stop. You are designing procedures, not scoping the product. Move the procedures to an activity diagram.

PlantUML keeps use case diagrams in version control. Start with left to right direction so actors sit beside the boundary. Declare actors, then a rectangle for the system, then usecase aliases, then associations.

Open the PlantUML online guide if you want a broader text-to-UML workflow. For this diagram type, the important keywords are actor, rectangle, usecase, and the include or extend arrows.

After you paste the example into the homepage editor, rename the product and add one actor you actually have (Support, Partner, Batch job). Export PNG or SVG for the slide deck. Keep the .puml (or the editor localStorage) as the source of truth.

A compact shop diagram:

Skip this diagram when the audience already agrees on actors and goals, and you need algorithms, states, or class structure. Skip it when the product is a library with no human actors unless you treat calling applications as actors.

Do not use use case diagrams to show sequence of screens. Do not use them as a project plan (no dates). Do not invent actors for every persona variant if they share the same goals.

If the workshop turns into a debate about include versus extend for twenty minutes, you have enough UML. Write the scenarios in a table and move on. The diagram's job is alignment, not completeness.

Putting system internals (database, cache) as use cases. Those are components.

Drawing every REST endpoint as an oval. Endpoints are how you implement a goal, not the goal.

Actors inside the boundary. If they are inside, they are not actors.

Unnamed associations that cross the whole page. If an actor relates to eight ovals, split the diagram by subsystem.

Mixing tense and grammar (Order placement vs Place order). Pick verb phrases and stick to them.

Forgetting secondary actors that the system must call. Payment and email often belong on the picture because they constrain scope and SLAs.

Each use case should map to at least one happy-path test and a few negative tests. Name the tests after the use case so coverage reports stay readable. Sequence diagrams for Place order will show the services; activity diagrams will show branches like out of stock.

In code, a use case often becomes an application service or a command handler. That mapping is a design choice, not a UML rule. The class diagram best practices post covers how to keep the domain model from mirroring the UI.

Keep the use case diagram in the same repo as the product, next to the README or an architecture folder. When a new actor appears (for example a marketplace seller), update the diagram in the same pull request as the feature flag.

Draw your product's actors and five to nine use cases in the free UML diagram tool. Compare with the use case gallery example. Then pick one oval and expand it as an activity diagram or a sequence diagram. If you are new to UML overall, start with the getting started guide.

The picture is done when a new teammate can point to who is outside the system and what they are trying to achieve. That is the whole job of this diagram type.