Use case descriptions: from brief to fully dressed

A use case diagram shows what will be done but gives no detail. The use case description gives the detail: how the actor interacts with the system step by step, what can go wrong, and what is true when it ends. This text is the input for both the designer and the tester: every alternate flow turns into a test case. A typical exam question: “Write a fully dressed use case description for X.” Know the template by heart, write the steps in proper sentences, and don’t skip the alternate flows.

Golden rules:

1. The normal flow is a single successful scenario. Errors and options go under a separate heading.
2. The subject of every step must be clear: “The student …”, “The system …”. No passive sentences.
3. Deviations are written with a step number: “4a. If the book is already reserved …”.
4. The same level of abstraction. One step shouldn’t be “selects a book” and another “moves the mouse to the right”.

Three levels of detail

There are also two further distinctions:

• Overview vs detail: An overview use case is high level (usually a brief), a detail use case gives the full flow.
• Essential vs real: An essential use case is independent of technology (“The student selects the book”). A real use case describes a specific interface (“The student taps the ‘Reserve’ button”). In analysis, write essential.

The fully dressed template

Some templates also include a “special requirements” field: the nonfunctional requirements belonging to this use case (e.g. “The reservation confirmation within 3 s”).

Rules for writing steps

1. The SVDPI pattern: Subject - Verb - Direct object - Preposition - Indirect object. “The system (S) sends (V) the confirmation e-mail (D) to the student (I).” Word order may vary; what matters is that the subject and the object are clear.
2. Make clear who starts it. Every step is an action of either the actor or the system.
3. Write like an independent observer. Not “I press the button” but “The student submits the request.”
4. The same level of abstraction. Screen details (color, button position) do not go into an analysis description.
5. A reasonable number of steps. 3-9 steps is ideal. If it is too long, split it into a subflow or a separate use case.
6. Keep it simple (KISS). Don’t stuff every possible case into the normal flow.
7. Write the return instruction. At the end of an alternate flow, state where to go back to: “return to step 4” or “the use case ends”.

PITFALL · writing the normal flow with if/else. A sentence like “If the book is available, it reserves it; otherwise it adds to the waiting list” does not belong in the normal flow. The normal flow describes the available case; the not-available part is written as “4a” in the alternate flows.

Worked example: Reserve Book (fully dressed)

Context: The reservation system of a campus library. The student reserves an available book for 48 hours, and the book is held at the lending desk.

Use case name : Reserve Book
ID            : UC-04
Importance    : High
Primary actor : Student
Use case type : Detail, essential

Stakeholders and interests:

• Student: to get the book they want without waiting in a queue.
• Librarian: orderly reservations and few no-shows.
• Library manager: fair use of resources.

Brief description: The student searches for a book and reserves an available copy for 48 hours; the system sets the copy aside and sends the confirmation.

Trigger: The student wants to reserve a book. Trigger type: External.

Relationships:

• Association: Student
• Include: Verify Membership
• Extend: Join Waiting List
• Generalization: none

Preconditions:

• The student is logged in to the system.
• The library catalog is up to date.

Normal flow of events:

1. The student searches for the book by title,
   author or ISBN.
2. The system lists the matching books and the
   number of available copies of each.
3. The student selects a book and a pickup branch.
4. The system runs the S-1: Check Eligibility
   subflow.
5. The system sets aside an available copy
   in the student's name for 48 hours.
6. The system creates the reservation record and
   generates a reservation code.
7. The system sets the status of the copy to
   "On Hold".
8. The system shows the confirmation on screen and
   sends an e-mail to the student.

Subflows:

S-1: Check Eligibility
 1. The system verifies that the student's
    membership is active (Verify Membership).
 2. The system checks that the student has
    no unpaid fines.
 3. The system checks that the student's number
    of active reservations is less than 3.

Alternate / exceptional flows:

2a. If there is no matching book:
    2a1. The system says "No results found".
    2a2. Return to step 1.
3a. If the selected book has no available copy:
    3a1. The system offers to join the waiting
         list (extend: Join Waiting List).
    3a2. If the student accepts, they are
         added to the list; the use case ends.
S-1.2a. If there is an unpaid fine:
    The system shows the fine amount and
    rejects the reservation; the use case ends.
S-1.3a. If the number of active reservations is 3:
    The system shows a limit message;
    the use case ends.
5a. If the copy was set aside by someone else
    in the meantime:
    The system informs the student, return to step 2.

Postconditions:

• Success: A copy is “On Hold” in the student’s name for 48 hours, and the reservation record and code exist.
• Failure: The status of no copy has changed.

Analyzing the example

• The normal flow has 8 steps. The subject of every step is clear: the Student (1, 3), the System (2, 4-8).
• The eligibility check was put into a subflow, and the main flow stays readable.
• Verify Membership is an include because it is also used in other use cases (Borrow Book).
• Join Waiting List runs only if there is no copy: an extend, triggered in alternate flow 3a.
• 5a catches a concurrency problem. Deviations of this kind turn into a locking requirement in the design.

From the description to other models

The description is the raw material for the following weeks:

Common mistakes