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.
Implementation use cases
- The use cases documented here should be for product implementations where a data receipt of some kind is utilized.
- The Kantara Receipt Specification describes a data structure and output format.
- The implementation use cases describe, from the perspective of the Actors, how the Actors succeed or fail to accomplish their objectives with respect to the "System".
The overall objective of this use case collection exercise is to substantiate proposals for enhancement of the Kantara Consent Receipt Specification v1.1. New uses with requirements beyond those supporting v1.1 are anticipated. The WG will decide if or how to accommodate these new requirements. Drastic changes to Version 1.1 are not expected - the core use cases around regulatory compliance remain intact.
Use Case Writing Guidance
A use case is a description of the possible sequences of interactions between the system under discussion and its external actors, related to a particular goal.
- The use cases should be written as if the purpose (main goal) of the 'system' is creation, issuance, management and consumption of receipts. This is an odd viewpoint but it should help to clarify what data fields, semantics and non-functional needs exist for the receipts themselves.
- For each use case, there is likely to be more than one Primary Actor. The text of the Main Success Scenarios are written in a way to explain how the goals of the Primary Actor are satisfied. If there is more than one Primary Actor, write parallel use cases with the focus on the additional primary actors. Be careful when deciding if there is more than one Primary Actor - the use case analysis will be more complex with multi-primary situations.
- Flow diagrams are helpful to explain the use case text - but the text should be the main way of describing and understanding the use case, not the picture.
The remainder of the content on this page is a longer description about use case writing and suggestions for content and process.
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:
- A use case is a prose essay
- Make the use case easy to read
- Sentences should be present tense; with an active verb in active voice; describing an actor successfully achieving a goal that moves the process forward.
- Incude sub-use cases where they make sense
- Each sentence must have an actor acting
- Get the goal level right - the use cases should have no more than 10 steps in them
- Keep the GUI out of the use case
- Each use case should describe the successful ending and the failure ending
- 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.
- 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.
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 Actor||Is Actor?||Goal or Interest|
|Data Controller DPO||Y||Goal 1 (the actor's goal)|
|Interest 1 (the system guarantee)|
|The Individual||Y||Goal 2 (the actor's goal)|
|Regulator||N||Interest 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 receipt management 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.
|Actor (from A-G List)||(from A-G List)||Success flow, in summary.|
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 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.
|Use Case Name||A short name|
|Scope||The name of the system or business area or business function operated|
|Context||Text about the goal in its operational context|
|Primary Actor||The primary actor name or role|
|Stakeholders & Interests||List 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 Guarantees||An optional section listing the minimal guarantees|
|Success Guarantees||An optional section listing the success guarantees|
|Preconditions||What must be true before this use case can be triggered|
|Triggers||What 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.