A Practical Style Guide and Templates Repository for Writing Effective Use Cases

An opinionated style guide for use case writing

Software developers are most effective when handed with a set of consistent and self-contained use cases. However, writing high-quality use cases is a difficult and time-consuming task. Inspired by the success of various coding style guides, we developed a use case writing style guide and a small set of use case templates to slightly constrain the way a use case is written. This style guide will help reduce excessive personal idiosyncrasy in use case writing and give a uniform appearance to the use case written by different requirements engineers so that it is much easier to understand a large set of use cases.

Instead of overly restricting the use case writing process, the purpose of this style guide is to find a balance between readability and creativity.

Note: The use case templates repository is available at here. A real project's use case specification following this style guide is available at here. Feel free to provide feedback.

Table of contents

1. Generic use case specification format
2. Use case naming
3. Actors
4. Trigger
5. Use case description
6. Action steps
7. Extensions
8. Data requirements
9. Business rules
10. Related use cases
11. Amendments

1. Generic use case specification format

• 1.1 We adopt the use case specification format from Software Requirements (Third Edition) by Karl Wiegers and Joy Beatty with slight modification as a basis for writing use cases.

UC ID and Name:
Created By:		Date Created:
Primary Actor:		Secondary Actors:
Trigger:
Description:
Preconditions:
Postconditions:
Main Success Scenario:
Extensions:
Priority:
Frequency of Use:
Business Rules:
Associated Information:
Related Use Cases:
Assumptions:
Open Issues:

⬆ back to top

2. Use case naming

• 2.1 Assign a unique ID to each use case.

  Rationale: This ensures that you can quickly identify one use case.

• 2.2 Start with a verb with the first letter capitalized and describe the goal of the user.
  • Positive example: UC-03: Request a SuperFrog appearance for TCU events
  • Negative example: SuperFrog appearance request management

⬆ back to top

3. Actors

An actor specifies a role played by a user or any other system that interacts with the system under development.

• 3.1 Use a singular substantive name. To highlight this characteristic, capitalize the actor's name.
  • Positive example: The Spirit Team Director <completes a task>.
  • Negative example: The spirit team director <completes a task>.

• 3.2 Include all actors participating in the use case.

  Note: Many use cases neglect to include some important secondary actors.

⬆ back to top

4. Trigger

A trigger is the initiator of a use case.

• 4.1 Use "The <Primary Actor> indicates to do . . . " or "The <Primary Actor> chooses to do . . . " to describe the trigger of the use case.
  • Positive example: The User indicates to search for products meeting defined search criteria.
  • Positive example: The User chooses to search for products meeting defined search criteria.

• 4.2 Trigger is the same as the first action step in the main success scenario.

• 4.3 If a use case has more than one trigger, pick one as the trigger and the first action step of the main success scenario and treat others as the extensions of the first action step.
  • For example, use case "Cancel a request" can be triggered either by the Spirit Director or by time, because one business rule states: "If a payment is not received 24 hours prior to the event date and time, request will be automatically canceled." In this case, we will make the human trigger as the first step in the main success scenario, "1. The Spirit Director indicates to cancel a request." Then in the extension section of the use case, we use "1a. Payment is not received 24 hours prior to the event date and time." to start an alternative success scenario.

⬆ back to top

5. Use case description

We require a one-sentence description for each use case.

• 5.1 Use "The <Primary Actor> wants to <completes a task> so that <goal and rationale>" to describe the gist of the use case in one sentence.

  Rationale: Use case description works as a summary of the use case. It is read by busy people.

⬆ back to top

6. Action steps

Use case action steps are sentences that form a use case's main success scenario and extensions. According to Alistair Cockburn, a use case action step either describes an interaction between two actors e.g., "The Customer enters address information." or a validation step to protect interest of a stakeholder e.g., "The System validates the credentials." or an internal change to satisfy a stakeholder e.g., "The System deducts amount from balance." Our style guide complements Cockburn's classic 10 action step writing guidelines by recommending proper words and sentence structures.

• 6.1 Use the following wording and sentence structure to describe the Primary Actor's intention (Corresponds to Cockburn's interaction between two actors)
  • The <Primary Actor> indicates to/selects to/chooses to/requests to/attempts to . . .
  • The <Primary Actor> submits . . .
  • The <Primary Actor> views . . .
  • The <Primary Actor> verifies . . . and confirms . . .
  • The <Primary Actor> enters/provides/specifies . . . and confirms she has finished entering.
  • The <Primary Actor> continues entering . . .
  • The <Primary Actor> . . . until confirming that she has finished . . .
  • The <Primary Actor> acknowledges . . . (e.g., the alert or warning) and confirms to continue.
  • The <Primary Actor> ignores the warning/alarm and confirms to continue.

• 6.2 Use the following wording and sentence structure to describe the system internal processing (Corresponds to Cockburn's validation step and internal change)
  • The System validates, saves, records, calculates, updates, deletes, creates, retrieves, triggers . . .

• 6.3 Use the following wording and sentence structure to describe an interaction started by the System (Corresponds to Cockburn's interaction between two actors)
  • The System displays/shows/presents/informs . . . according to . . . defined in the Associated Information of this use case. (This is usually the information retrieved from a data source. For example, a list of products or a graph of stats. The previous action step may be "The System retrieves . . . ")
  • The System alerts/warns/alarms . . . (This is used when something is about to break the business rule, or something is about the change the state of the system, usually occurs in extensions.)
  • The System asks the <Primary Actor> to enter . . . according to . . . defined in Associated Information of this use case.
  • The System prompts the <Primary Actor> . . . (The system knows some information that would help the user decide what to do next) or The System offers . . . options/methods/choices . . .
  • The System notifies/sends <Secondary Actors> . . .

• 6.4 Use the following wording and sentence structure to describe an interaction between the System and another system in the environment (Corresponds to Cockburn's interaction between two actors)
  • The System has another system do something.
  • The System requests another system to do something.
  • Another System provides . . .

• 6.5 The System always provides feedback that the requested task has been finished. This allows the User to know the command has been completed, even if it is not immediately obvious.
  • Positive example: The System indicates that the calculation is finished.

• 6.6 The User always provides feedback to the System.
  • Positive example: The User confirms that the . . . is complete.
  • Positive example: The System processes . . . and indicates to the User . . . , then the User acknowledges the indication.

• 6.7 The first sentence in the main success scenario must report the event that activates the execution of the functionality described in the use case.

• 6.8 Use "Use case ends." to explicitly indicate the end of a use case.

• 6.9 When including another use case, use "The User or System <completes a task> through UC-<ID>: <Use Case Name>."

⬆ back to top

7. Extensions

An extension describes either an exception of a step in the main success scenario or an alternative success scenario.

• 7.1 Use the following wording and sentence structure to describe the handling of use case extensions.
  • The System alerts the <Primary Actor> that an input validation rule is violated and displays the nature and location of the error.
  • The <Primary Actor> corrects the mistake, then returns to step . . . of normal flow.
  • The <Primary Actor> chooses to terminate the use case.

⬆ back to top

8. Data requirements

It is recommended to include data requirements when specifying a use case. We use terminologies like "details" or "property lists" to denote data requirements.

• 8.1 Use tabular format to describe the Primary Actor's input and the System's output data in Associated Information section of a use case . Each row describes one detail or property. Each column represents one characteristic of interest to the action steps in the use case.

  Property name	Data type	Changeability	Validation rule	Glossary

⬆ back to top

9. Business rules

Business rules include corporate policies, government regulations, laws, industry standards, and computational algorithms.

• 9.1 Specify related business rules (e.g., security and access control requirements) in the business rules section.
  • Identify any relevant business rules concerning security/access.
  • Specify more finer-grained access control.
  • Specify any limitations regarding which individuals, groups, or organizations are permitted to initiate this use case or which data they are permitted to access.

⬆ back to top

10. Related use cases

• 10.1 Provide related use cases.

  Rationale: This is incredibly useful for software architecture design and UI design. E.g., "View a <whatever>" is related to "Find <whatever> s."

⬆ back to top

11. Amendments

We encourage you to fork this guide and change the rules to fit your team's use case writing style guide. Below, you may list some amendments to the style guide. This allows you to periodically update your style guide without having to deal with merge conflicts. ⬆ back to top