How to detail a use case?
To fully describe a use case (UC), you can use the following set of parameters:
Let’s break it down step-by-step, with examples.
To fully describe a use case (UC), you can use the following set of parameters:
- ID + Name
- Brief Description
- Actors
- Triggers
- Preconditions
- Postconditions
- Scenarios: basic, alternative, and exceptions
- Other additional points
Let’s break it down step-by-step, with examples.
ID + Name
The identifier should be self-explanatory. Key requirements (such as individual solution scope items) must be uniquely identified for consistent referencing — this is foundational in requirements documentation. What you choose as the ID format is up to you. For example: UC-01.
As for naming, it's best to stay consistent in your approach. I recommend using an infinitive verb: what to do? Usually, some clarification follows the verb — at the very least, it will reference the object of the action.
So, for an ATM: UC-01 Withdraw Cash
For a news portal: UC-03 View News
The identifier should be self-explanatory. Key requirements (such as individual solution scope items) must be uniquely identified for consistent referencing — this is foundational in requirements documentation. What you choose as the ID format is up to you. For example: UC-01.
As for naming, it's best to stay consistent in your approach. I recommend using an infinitive verb: what to do? Usually, some clarification follows the verb — at the very least, it will reference the object of the action.
So, for an ATM: UC-01 Withdraw Cash
For a news portal: UC-03 View News
Brief Description
This section should outline the essence of the use case and the value it brings to the primary actor. It’s optional, but I strongly recommend including it — it saves the reader from needing to study the scenario to grasp what the UC is about. Focus on conveying the value to the actor, rather than simply duplicating the name — that would be pointless.
Examples:
This section should outline the essence of the use case and the value it brings to the primary actor. It’s optional, but I strongly recommend including it — it saves the reader from needing to study the scenario to grasp what the UC is about. Focus on conveying the value to the actor, rather than simply duplicating the name — that would be pointless.
Examples:
- The actor withdraws a specific amount of cash from their account using a bank card in order to obtain cash.
- The actor views the content of a specific news item on the portal to gain detailed information.
Actors
List all primary and secondary actors involved in the use case. Clearly label who is who. To ensure maintainability (one of the hallmarks of high-quality requirements), avoid duplicating actor names throughout the UC. Instead, simply refer to "Actor" (with a note if they are primary or secondary when needed). Don’t use “User” or “Administrator” in every section — keep it abstracted.
List all primary and secondary actors involved in the use case. Clearly label who is who. To ensure maintainability (one of the hallmarks of high-quality requirements), avoid duplicating actor names throughout the UC. Instead, simply refer to "Actor" (with a note if they are primary or secondary when needed). Don’t use “User” or “Administrator” in every section — keep it abstracted.
Triggers
An optional section. Triggers are what cause the use case to begin. In most cases, this will be the actor’s desire (a motivational impulse to start the UC). But sometimes it's something else, like: "It’s 4:00 PM in time zone X." — in such cases, when it’s not obvious (e.g., "Actor wants to view news"), the trigger should be stated explicitly here.
An optional section. Triggers are what cause the use case to begin. In most cases, this will be the actor’s desire (a motivational impulse to start the UC). But sometimes it's something else, like: "It’s 4:00 PM in time zone X." — in such cases, when it’s not obvious (e.g., "Actor wants to view news"), the trigger should be stated explicitly here.
Preconditions
These are the conditions that must be met for the UC scenario to even begin (not to complete it successfully). They serve as constraints for starting the UC. Essentially, preconditions depend on where your UC scenario begins. To define preconditions, ask yourself (or the stakeholders, if needed):
Your answers to the second question will be the preconditions.
Example: UC-01 Withdraw Cash
Q1: First step — "Actor inserts bank card into ATM"
Q2: "ATM card slot is empty" (what if someone left their card or jammed something inside?)
Example: UC-03 View News
Q1: First step — "Actor opens news item from the feed". Note that here, unlike the previous example, the actor already sees the news feed at the start.
Q2: "News feed is displayed with at least one news item listed". You may also trace this to a successful result of another UC, e.g.: "News feed is displayed with at least one news item listed (see UC-02 View News in a Category)."
These are the conditions that must be met for the UC scenario to even begin (not to complete it successfully). They serve as constraints for starting the UC. Essentially, preconditions depend on where your UC scenario begins. To define preconditions, ask yourself (or the stakeholders, if needed):
- What marks the start of the UC? What’s the first step and who performs it?
- What must the system check to allow that first step to happen?
Your answers to the second question will be the preconditions.
Example: UC-01 Withdraw Cash
Q1: First step — "Actor inserts bank card into ATM"
Q2: "ATM card slot is empty" (what if someone left their card or jammed something inside?)
Example: UC-03 View News
Q1: First step — "Actor opens news item from the feed". Note that here, unlike the previous example, the actor already sees the news feed at the start.
Q2: "News feed is displayed with at least one news item listed". You may also trace this to a successful result of another UC, e.g.: "News feed is displayed with at least one news item listed (see UC-02 View News in a Category)."
Postconditions
These are the conditions/facts/states that are true when the UC is successfully completed. You can optionally include postconditions for exception scenarios too, though this is less common. Postconditions may be visible results for the actor or internal system changes. At a minimum, include the successful result. Anything else is up to your discretion.
Examples:
These are the conditions/facts/states that are true when the UC is successfully completed. You can optionally include postconditions for exception scenarios too, though this is less common. Postconditions may be visible results for the actor or internal system changes. At a minimum, include the successful result. Anything else is up to your discretion.
Examples:
- The cash dispensing slot contains the amount withdrawn.
- The corresponding amount has been deducted from the actor’s linked bank account.
- A receipt is available in the receipt slot showing transaction details.
- The screen shows the details of the selected news item.
Scenarios
A scenario is a sequence of steps performed by the actor(s) and the system to fulfill the UC. This is where most functional requirements lie — it’s the system logic triggered by user actions.
Often, scenarios are written like a “ping-pong”: Actor action → System response → Actor action → System response, etc.
There are two main approaches to scenario description:
Most theories advocate for the first, but both are valid. Use what fits your context. If UI isn’t your concern or is handled elsewhere, use interface-agnostic. If UI components are central to the requirements and not documented elsewhere, it makes sense to include them.
Basic Scenario – UC-01 Withdraw Cash
Basic Scenario – UC-03 View News
In the final step, note the extension point — where the actor may initiate a related UC. The UC-04 scenario would begin with a step like: “Actor enters comment text and submits.” To reflect inclusion, simply embed the included UC as a step: e.g., step 3: "See UC-05..." Inheritance between UCs is a more advanced topic and is beyond the scope of this post.
Alternative Scenarios
Alternative scenarios are those that also lead to a successful outcome but differ in some steps. They may:
Alternative Scenario A – Actor Enters Amount Manually
8.1a. Actor selects manual input.
8.2a. System prompts for amount.
8.3a. Actor enters amount and confirms.
Explanation:
Exceptions
These do not lead to a successful outcome. They include errors (actor-related or not), cancellations, and other exceptions. They’re vital — you must consider and define them, or developers won’t implement handling.
Examples:
Exception B – Invalid PIN
5b. System shows incorrect PIN message. Return to step 3.
Exception C – Insufficient Funds in ATM
10c. System shows message about unavailable funds. Return to step 7.
(Note: Poor UX — the actor is guessing viable amounts)
Exception D – Secondary Actor Unavailable
11d. System displays message: operation not available at this time.
(Bad UX — actor is stopped near the end of the flow)
Exception E – Printer Out of Ink/Paper
13e. System shows message: receipt cannot be printed.
(Bad UX — actor may want to cancel if receipt is critical)
Exception F – Actor Cancels Operation
2f–8f. Actor cancels operation.
9f. System ejects card.
A scenario is a sequence of steps performed by the actor(s) and the system to fulfill the UC. This is where most functional requirements lie — it’s the system logic triggered by user actions.
Often, scenarios are written like a “ping-pong”: Actor action → System response → Actor action → System response, etc.
There are two main approaches to scenario description:
- Interface-agnostic: No mention of UI specifics, e.g., “Actor saves Order.”
- UI-based: Includes interface terms, e.g., “Actor clicks the 'Save' button to save Order.”
Most theories advocate for the first, but both are valid. Use what fits your context. If UI isn’t your concern or is handled elsewhere, use interface-agnostic. If UI components are central to the requirements and not documented elsewhere, it makes sense to include them.
Basic Scenario – UC-01 Withdraw Cash
- Actor inserts bank card into ATM.
- System prompts for PIN.
- Actor enters PIN and confirms.
- System verifies the PIN.
- System displays available operations.
- Actor selects "Withdraw Cash."
- System asks for withdrawal amount.
- Actor chooses amount from displayed options.
- System checks if requested amount is available in the cash reserve.
- System sends request to secondary actor to deduct funds from account.
- System receives confirmation from secondary actor.
- System dispenses requested cash.
- System prints a receipt with transaction details.
Basic Scenario – UC-03 View News
- Actor opens desired news item from the news feed.
- System displays the news content. Can be extended by UC-04 Comment on News.
In the final step, note the extension point — where the actor may initiate a related UC. The UC-04 scenario would begin with a step like: “Actor enters comment text and submits.” To reflect inclusion, simply embed the included UC as a step: e.g., step 3: "See UC-05..." Inheritance between UCs is a more advanced topic and is beyond the scope of this post.
Alternative Scenarios
Alternative scenarios are those that also lead to a successful outcome but differ in some steps. They may:
- Start differently and later converge
- Start the same and diverge mid-way
- Have a combination of both
- Be fully parallel
Alternative Scenario A – Actor Enters Amount Manually
8.1a. Actor selects manual input.
8.2a. System prompts for amount.
8.3a. Actor enters amount and confirms.
Explanation:
- Only step 8 of the basic scenario is replaced here.
- The "a" suffix identifies the scenario and its steps as unique.
Exceptions
These do not lead to a successful outcome. They include errors (actor-related or not), cancellations, and other exceptions. They’re vital — you must consider and define them, or developers won’t implement handling.
Examples:
Exception B – Invalid PIN
5b. System shows incorrect PIN message. Return to step 3.
Exception C – Insufficient Funds in ATM
10c. System shows message about unavailable funds. Return to step 7.
(Note: Poor UX — the actor is guessing viable amounts)
Exception D – Secondary Actor Unavailable
11d. System displays message: operation not available at this time.
(Bad UX — actor is stopped near the end of the flow)
Exception E – Printer Out of Ink/Paper
13e. System shows message: receipt cannot be printed.
(Bad UX — actor may want to cancel if receipt is critical)
Exception F – Actor Cancels Operation
2f–8f. Actor cancels operation.
9f. System ejects card.
Additional Points
Use this section for anything else you'd like to document. Typical examples:
Use this section for anything else you'd like to document. Typical examples:
- References to related UCs
- Links or mockups for UI mentioned in this UC
- Any supporting requirements, such as: non-functional (performance, usability, etc.), interfaces with secondary actors (data mappings, request/response formats), data requirements (entities, attributes), UI constraints (component visibility, validation, etc.)
And that’s it. Once you combine all the above sections, you’ll have a full UC specification. Describe all UCs similarly and add a UC diagram — and you’re nearly done with your system requirements spec.
Of course, use cases aren’t the only tool in a BA’s toolbox, but for the goals outlined at the start, they’re extremely effective. Go ahead and use them — everything in this post should cover the vast majority of your needs.
Of course, use cases aren’t the only tool in a BA’s toolbox, but for the goals outlined at the start, they’re extremely effective. Go ahead and use them — everything in this post should cover the vast majority of your needs.