Use Case style and instructions

To promote consistency in the contributed content, please read these style and composition notes for use cases. Thank you.

The guidance here is from the book Writing Effective Use Cases by Alistair Cockburn. The intent is to provide guidance to produce the smallest, essential parts of a use case.

Page Contents

Reminders for Use Case Writers

The use case style is oriented to text descriptions of how the system behaves with respect to a list of Actors.

The book has a list of reminders for writers:

  1. A use case is a prose essay
  2. Make the use case easy to read
  3. Sentences should be present tense; with an active verb in active voice; describing an actor successfully achieving a goal that moves the process forward.
  4. Incude sub-use cases where they make sense
  5. Each sentence must have an actor acting
  6. Get the goal level right - the use cases should have no more than 10 steps in them
  7. Keep the GUI out of the use case
  8. Each use case should describe the successful ending and the failure ending
  9. Stakeholders (of which the primary actor is one) have expectations that must be met by the system

Recommended Sequence for Writing

The book recommends the following order when writing:

NOTE: We expect to collect existing use case documents whenever possible rather than directly analysing organization processes, so this list can be viewed as an analysis appraoch when translating the contributions into a common style.

Gather information

  • Step 1: Find the boundaries of the system (Context diagram, In/out list).
  • Step 2: Brainstorm and list the primary actors. (Actor List) 
  • Step 3: Brainstorm and list the primary actors' goals against the system. (Actor-Goal List) 

Describe the highest-level summary use case that covers all of the actors and their goals

  • Step 4: Write the outermost summary level use cases covering all the above. 
  • Step 5: Reconsider & revise the strategic use cases. Add, subtract, merge goals. 

Select and write a use case document

  • Step 6: Pick a use case to expand or write a narrative to get acquainted with the material. 
  • Step 7: Fill in the stakeholders, interests, preconditions and guarantees. Double check them. 
  • Step 8: Write the main success scenario. Check it against the interests and the guarantees. 

Extend to cover failure conditions

  • Step 9: Brainstorm and list possible failure conditions and alternate success conditions. (these become the 'extensions')
  • Step 10: Write how the actors and system should behave in each extension. 

Repeat with sub-use cases if needed and refine

  • Step 11: Break out any sub use case that needs its own space. 
  • Step 12: Start from the top and readjust the use cases. Add, subtract, merge. Double check for completeness, readability, failure conditions.


Some Potentially Useful Artifacts

This section describes some artifacts that might be useful when analysing use cases. Use of these is not mandatory, but can help to tease out the right level of detail.

The In/Out of Scope List

A simple list of topics about the system and an indication of whether the topic is in or out of scope for the system's use case description. Useful at the start of the exercise, and later, to remind the team of the functional scope of the system. 

TopicInOut
Topic 1In
Topic 2
Out

For this DG, functional topics related to identity assurance processes would typically be IN scope, while external processes or software details that support the assurance processes are probably out of scope (those are likely to be pre-conditions)

The Actor-Goal List

The Actor-Goal List captures the list of Actors that interact with the system, and their goals with respect to that system. The system operates a 'contract' between stakeholders; the use cases describe the functional behaviour of that contract. Stakeholders that are not present in the interaction have vested interests that should be satisfied (these might be understood as 'system guarantees'). Actors are a subset of Stakeholders.

Stakeholder or ActorIs Actor?Goal or Interest
ID Proofing ManagerYGoal 1 (the actor's goal)


Interest 1 (the system guarantee)
The IndividualYGoal 2 (the actor's goal)
RegulatorNInterest 2 (the system guarantee)

We expect that analysis of the contributed use cases will result in a core list of stakeholders that are common to the identity assurance processes plus additional stakeholders that relate to process-specific or regulation-specific activities.

The Use Case Brief

The use case brief is a 2-6 sentence description of the behaviour of the system from the point of view of each actor in turn. It might simply be a short description of the main success flow. It is a brief expansion of the actor's Goal statement.

ActorGoalBrief
Actor (from A-G List)(from A-G List)Success flow, in summary.

System Guarantees

Minimal Guarantee

Minimal guarantees are what the system promises to the stakeholders, in particular when the primary actor's goal cannot be achieved. These are not the same as failure scenarios, but might be related to them.

The idea is that the minimal guarantees will satisfy the stakeholders that their interests have been protected when the goal does not succeed.

Success Guarantee

Success guarantees are what the system promises to the stakeholders at the conclusion of the main success scenario. It includes all of the MInimum guarantees, plus. It includes the main goals of the use case.

To figure out what the success gaurantees might be for each stakeholder, ask the question 'what would make the stakeholder unhappy at the end of a successful run?' then use the negative of the answer.


Suggested Template for a Use Case

To reduce the burden and processing load on contributors, we will use a casual format. 

HeadingContent guidance
Use Case NameA short name
ScopeThe name of the system or business area or business function operated
ContextText about the goal in its operational context
Primary ActorThe primary actor name or role
Stakeholders & InterestsList of all the stakeholders and their interests in the system operation. Stakeholders include actors that interact with the system and others who do not interact with the system.
Minimal GuaranteesAn optional section listing the minimal guarantees
Success GuaranteesAn optional section listing the success guarantees
PreconditionsWhat must be true before this use case can be triggered
TriggersWhat causes the main scenario to start
Main Success Scenario

A brief list of what the actors do which results in the goal being successfully achieved.

A second brief list of what the actors do when things don't go down the main path - includes alternative paths and major failure conditions.