Specifications

Objective

1. Understand the importance of specifications in software development.
2. Document use cases and structuring specifications.
3. Specify main success scenarios and alternative flows.
4. Identify system responses to actor actions.

Specifications

Regardless of the level of formality, use cases should always be written in clear, natural language that is easily understood by both technical and non-technical stakeholders. It is important to remember that use cases are described from the user’s perspective, focusing on what they want to accomplish rather than the system’s inner workings.

The use case should explicitly outline the user’s goals and the tasks they need to complete to achieve those goals, using terminology and language familiar to them. This approach ensures that the use case reflects the user’s experience and needs, avoiding technical jargon or implementation details that could cause confusion.

The goal is to capture the essence of the user’s interactions with the system, highlighting the steps they take to achieve their objectives and the outcomes they expect. This user-centric language helps to align development efforts with real-world use, ensuring that the system meets the intended user requirements.

Triggers

A trigger is an event that initiates a sequence of actions within a system or application. Triggers can come from external factors like user interactions, system-generated events, or third-party services. They provide the “when” of the use case, indicating the conditions that must be met for the flow to begin.

For example, in an e-commerce platform, the trigger could be when a customer clicks the Buy Now button, which starts the checkout process. Triggers are key in activating use cases and determining the start of a flow within the system.

Flows

Flows describe the sequence of steps that a system goes through once a trigger has occurred and conditions are met. They can be broken down into main flows (the primary sequence of actions, that is, the main success scenario) and alternative flows (other paths based on conditions or errors). They provide the “how” of the use case, while goals and triggers provide the “why” and “when”, respectively.

For instance, in a checkout process, the main flow would involve selecting payment, confirming the order, and receiving a receipt. An alternative flow could occur if the payment fails, prompting the user to retry or choose another payment method. Flows outline the paths and outcomes of user and system interactions.

Behaviors

Behaviors can be described either through natural language text (opaque behavior), which is the most common approach today, or through UML behavior diagrams, such as activity, state machine, or interaction diagrams, for more specific behaviors. Alternatively, the behavior of a use case can be conveyed indirectly through a collaboration diagram that shows interactions between the use case and its actors, using them as classifiers for the parts involved.

The choice of technique depends on the complexity of the use case and the audience for whom the description is intended. These approaches are not mutually exclusive and can be combined for clarity. UML tools should support linking behaviors directly to the described use case. The use case itself can be displayed within a frame labeled as either use case or uc (the abbreviated form), with the content area represented by various UML diagrams that illustrate its behavior.

Conditions

Conditions refer to the criteria or state that must be met before the flow can proceed. These can be preconditions or postconditions. Preconditions are requirements that must be fulfilled before a use case starts, such as a user being logged in or an item being in stock. Postconditions are the expected outcomes once a use case is completed, like confirmation of payment or a receipt of an order. Conditions ensure that the flow follows specific rules and validations. They provide the “what” of the use case, indicating the state of the system at different stages of the flow.

Template

Exercise 1

Specify two use case details in use-case-01.md and use-case-02.md, using the following template:

- Name:
- Description:
- Primary actor:
- Goal:
- Triggers:
- Preconditions:
- Postconditions:
- Main scenario:
  1.
  2.
- Extensions:
- Special requirements:

Action-Response Table

An actor-action-system response table is a structured way to document and clarify the interactions between users (actors) and a system during a use case. It helps define the sequence of actions taken by the actor, what the system does in response, and how these interactions progress toward achieving a specific goal. This format is often used to capture use case flows in a detailed, step-by-step manner, providing both technical and non-technical stakeholders with a clear view of how the system should behave.

1. Actor: Represents the user or external entity interacting with the system.
2. Action: The task or command performed by the actor (e.g., clicking a button, entering information).
3. System Response: The reaction of the system to the actor’s action, for example, validating data, displaying a message.

Example

This table helps map out the back-and-forth interaction between the user and the system, ensuring all flows are covered. It is particularly useful for defining both primary and alternative scenarios, such as error handling or system failures.

Exercise 2

Rewrite the flows from Exercise 1 in an actor-action system-response table using the following template:

| Step | Actor Action | System Response |
| :--- | :----------- | :-------------- |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |
|      |              |                 |

Exercise 3

Create a use case diagram, use-cases.vpp, that includes the details that were specified in Exercise 2 using Visual Paradigm.

Structure

Resources

• Visual Paradigm: Documenting use case details (opens in a new tab), How to write effective use cases? (opens in a new tab)
• UML diagrams (opens in a new tab)