# Cockburn use case writing guide A short working reference for *Writing Effective Use Cases* (A. Cockburn). The goal is not to retell the book. It is to give what you actually use when you write. --- ## 1. What a use case is (and is not) A use case is a **contract about system behaviour**. It describes every scenario in which an actor tries to reach a goal by interacting with the system. A use case is a set of scenarios tied to **one goal**, not a single linear scenario. - Write it as **text**, not diagrams. UML "stick figures with arrows" is a use case map, not a use case. - It describes **behaviour**, not UI, not data structure, not architecture. - Phrase it from the point of view of the one who has the goal, in **active voice**: "The cashier enters the item", not "The item is entered". Cockburn's rule: write so the customer can read it and nod, and the developer can build from it. --- ## 2. Three axes every use case lives on Before you write the steps, pick three things for the UC: 1. **Scope** — what you treat as "the system" (the black box). 2. **Goal level** — how high or low the goal sits. 3. **Primary actor** — whose goal you serve. ### 2.1. Scope (design scope) This sets the black box boundary. It is named by the `scope` keyword in the UC frontmatter: | `scope` (frontmatter) | What the box holds | |-----------------------|-------------------| | `enterprise` | The whole organization | | `system` | The system you build, end to end | | `subsystem` | One module or service | The same goal can sit at different scopes. Keep whose box it is in your head, or the steps drift between business and system levels. ### 2.2. Goal levels — the "sea level" metaphor | `level` (frontmatter) | Meaning | Example | |----------------------|---------|---------| | `summary` | **Umbrella goal**. Strategic, covers several user goals | "Manage customer orders" | | `user-goal` ⭐ | **Sea level**. One task the actor finishes in one go. Primary level | "Place an order" | | `subfunction` | **Sub-step under water**. Helps a user goal | "Authenticate", "Find a customer" | | `too low` | **Too small** to be its own UC | "Verify a password against its hash" | **Practical rule.** Write most requirements at **`user-goal`**. Ask: "Can the actor walk away happy after one session?" If yes — sea level. If it is just one piece — subfunction. If it is the whole business goal for the day — summary. - **Summary** UCs decompose into user goals. - **User goals** reference **subfunctions** where a step repeats or is too detailed. - We rarely go down to `too low`. If you get lost with levels, start at `user-goal` and move up ("why is this needed?" → `summary`) or down ("how is this done?" → `subfunction`). --- ## 3. Formats (how dressed) Not every UC needs full dressing. Three levels of detail: - **Brief** — one paragraph, the essence of the scenario. Early stage or backlog. - **Casual** — several free-form paragraphs that cover the main path and the main deviations. - **Fully dressed** — the full template with every field (below). For critical or complex UCs. Keep most UCs at brief or casual. Fully-dress only the important ones. Do not polish what may still change. --- ## 4. Full template (fully dressed) ``` Title: — "Place an order" Level: user-goal / summary / subfunction Scope: Primary actor: Stakeholders and interests: - : - : Preconditions: Min. guarantees: Success guarantees: Trigger: Main success scenario: 1. 2. 3. <...> N. Extensions: 2a. : 2a1. 2a2. 3a. : 3a1. <...> Technology and data variations (optional): 1'. ``` --- ## 5. Key fields — how to fill them in **Title.** Always a verb that names the actor's goal: "Withdraw cash", "Publish an article". Not "Working with cash". **Stakeholders and interests.** The heart of the method. First, list who has a stake in the outcome and **what exactly** each one wants. The main scenario must then **satisfy all of these interests**. This guarantees completeness: you will not forget that the bank cares about security while the customer cares about speed. **Preconditions.** What the system has **already checked and treats as true** — not re-checked inside the UC. Do not write "the user wants..." here. **Guarantees.** - *Minimum* — what holds under **any** outcome, even on failure (for example, "the attempt is logged"). - *Success* — what holds when the goal is reached. **Trigger** — the event that starts the UC. --- ## 6. Main success scenario — step rules - **3 to 9 steps** per UC. More than that, and you probably want to move part into a subfunction. - Each step is a **simple active-voice statement** that shows **who** acts and moves the goal forward: ` `. - Write the **goal, not the UI**: "The user identifies themselves", not "types a login and presses Enter". Move UI to "technology and data variations". - Three step types: (1) actor↔system interaction, (2) the system validates or changes state, (3) the system works with internal data. - Number simply: 1, 2, 3... One scenario — one straight path with no "if". --- ## 7. Extensions — where all the complexity lives Everything outside the ideal path (errors, alternatives, deviations) goes into extensions. This is the main value of the format. - **Notation:** step number + letter. `3a`, `3b` — different conditions at step 3; `3a1`, `3a2` — steps inside condition `3a`. - Each extension starts with a **condition** (what became true), then the reaction steps. - The condition is a **fact**, not a check: "Card expired", not "Check the card date". - An extension ends with one of: return to a main scenario step, an independent success, or a failure (respecting the minimum guarantees). - To find all extensions, walk each step and ask: "what else can go wrong or different here?" --- ## 8. Links between use cases - A user-goal UC **calls** a subfunction as a step: "The user authenticates" (a link to the sub-step UC). Underline or capitalise it to mark it as a separate UC. - A summary UC **lists** its user goals as its steps. - Avoid deep include/extend hierarchies — they make the set unreadable. Reference a subfunction only if it **repeats** or **really clutters** the main flow. --- ## 9. Workflow (how to write step by step) 1. Make an **actor–goal list** — a table of "actor / their goal / level". This is the future registry at user-goal level. 2. For each, draft a **brief** (one paragraph). 3. Pick **priority and risk**. Fully-dress only the important ones. 4. For the chosen ones, write **stakeholders and interests** → **main success scenario** (success only, no "if") → **extensions** (walk every step). 5. Check with the checklist (below). 6. Iterate. A UC is a living document. Do not polish too early. --- ## 10. Quality checklist - [ ] Title = actor's goal in active form. - [ ] Scope (whose black box) and level (user-goal / summary / subfunction) are clear. - [ ] Primary actor is named; the goal is reachable "in one go" (for user-goal). - [ ] Stakeholders are listed; the main scenario covers **all** their interests. - [ ] Main scenario = ideal path, 3 to 9 steps, active voice, goals (not UI). - [ ] Each step moves the goal forward and is visible "from outside the box". - [ ] All deviations and errors live in extensions as condition-as-fact. - [ ] Preconditions and guarantees (minimum + success) are set. - [ ] No implementation leak (database, screens, fields) in the scenario body. --- ## 11. Common mistakes - **Too low** — the UC describes a click, not a goal. Ask "why?" and lift it to user-goal. - **UI instead of goals** — "presses Enter", "picks from a dropdown". Move to variations. - **Passive voice** — you lose who acts. - **`if` inside the main scenario** — all branching lives in extensions. - **Forgotten stakeholders** — the scenario is full, but someone's interests (security, audit, regulator) are not covered. - **CRUD mania** — four UCs ("Create/Read/Update/Delete") per entity instead of user-goal goals. - **Premature polish** — fully-dressing a UC that will change ten more times. --- ## 12. Mini example (user-goal level) ``` Title: Place an order Level: user-goal Scope: system Primary actor: Customer Stakeholders: - Customer: get the right goods, fast and without errors - Store: record a correct paid order Preconditions: The customer is authenticated; the cart is not empty Success guarantees: Order created, payment captured, warehouse notified Min. guarantees: Every attempt is logged; no money is charged without an order Main success scenario: 1. The customer confirms the cart. 2. The system computes the total (items, shipping, taxes). 3. The customer provides an address and a payment method. 4. The system captures the payment. 5. The system creates the order and notifies the warehouse. 6. The system confirms the order to the customer. Extensions: 2a. An item is out of stock: 2a1. The system marks the line as unavailable and offers to remove or replace it. 2a2. Return to step 1. 4a. Payment is declined: 4a1. The system reports the reason and offers another method. 4a2. Return to step 3. ``` --- **In one sentence:** pick the black box and the goal level → list stakeholders and their interests → write the ideal path in 3 to 9 active-voice steps → push all complexity into extensions → do not polish too early.