User story and use-case toolkit
Writing tools that capture the user’s perspective for a challenge statement.
Challenge statement writing tools
The challenge statement differs from more commonly used technical requirements or specifications. It uses an outcome-focused approach to define the buying objective, and the scope of the opportunity for the market.
This section discusses the differences in approach and provides guidance for writing high level use cases and user stories for a challenge statement.
Before writing a challenge statement, document authors should have a minimum foundational level of ICT scoping experience and skill, usually possessed by roles such as ICT Business analyst, Service designer or UX designer.
If you don’t have the foundational skills, and intend to undertake this activity yourself, please contact the innovation procurement advisory team at innovationprocurement@customerservice.nsw.gov.au for advice, support and guidance.
If you have the foundational skills, you may access the user story and use case toolkit. Note that these resources are undergoing testing and are available for guided use in conjunction with the Innovation Procurement advisory team. This ensures that the guides can tailor to project needs and incorporate any improvements.
To access expert resourcing to lead this activity, please contact the innovation procurement advisory team at innnovationprocurement@customerservice.nsw.gov.au. If you have any trouble accessing a file or document on this page, you can request an accessible version from the same email address.
At its simplest, a requirement is a service, function or feature that a user needs. Requirements can be functions, constraints, business rules or other elements that must be present to meet the need of the intended users. The success of any solution is the product of two aspects:
What it does
Functional requirements express functions or features and define what is required, but do not state how a solution will be physically achieved.
How well it performs
Performance is measured against defined parameters (non-functional attributes, acceptance criteria, service levels). Non-functional requirements define how well, or to what level a solution needs to behave. They describe solution attributes such as security, reliability, maintainability, availability (and many other “...ilities”), performance and response time. For example:
- responding within 2 seconds
- being available 24 hours per day, every day.
Requirements are typically expressed as an Institute of Electrical and Electronics Engineers IEEE 830 standard style specification, or a list that specifies ‘the system shall/must/should…’ statements, such as:
- the system must allow a company to pay for a job posting with a credit card
- the system shall give the user a unique confirmation number.
It's very difficult to write a list of specifications without assuming the solution.
Lists of specifications don't provide suppliers with the same overall understanding as a user story, which supplies key information about the user’s goal.
A user story is a well-expressed requirement. It is a note that captures what a user does or needs to do and their goal. Each user story consists of a short description written from a user's point of view, with natural language.
Unlike specifications, user stories focus on user needs and their goals instead of what the system should deliver. By looking at goals, suppliers get a contextual view of the proposed product or service. This leaves room for alternative solutions that can solve the business problems and add value.
User stories are written from the user's perspective:
- as a homeowner, I want something that makes it easy and fast for me to mow my lawn
- as a homeowner, I want a way to mow the lawn where I can sit down rather than stand up
User story benefits
The user story format is the most popular way of expressing requirements in innovation and agile buying projects and has many benefits.
User stories focus on the viewpoint of a person or role who will use or be impacted by the solution. This helps identify people or roles with a stake in the outcomes and who should have input to the requirements.
User stories help clarify the underlying reason for the requirement which ensures each requirement focuses on outcomes rather than solutions. They identifies user goals and address the business value of each requirement.
Users stories define the requirement in language that has meaning for that person or role. This strikes a good balance by defining high level requirements without going into detail.
User stories can be individually costed and prioritised, whereas with a specification the cost of each requirement is not made visible until all the requirements are written.
A well-written user story is clear, concise, and complete.
User stories should comprise:
- a unique ‘Story Identifier’ (a number or reference)
- a clear, explicit, short name or title
User story format
A user story has three parts:
As a <role>,
I need < > ,
so that < >.
This format covers, in order:
- the primary stakeholder (the user that derives benefit from the story)
- what effect the stakeholder wants the solution to have (the user’s need)
- what business value the stakeholder will derive from this effect.
User stories also include acceptance criteria, which consist of the outcome and measures of success.
The acceptance criteria defines high level criteria which will confirm if this user story is working as required.
Simple checks
For a user story to be effective, it should:
- not combine with, overlap nor conflict with other user stories
- conform to applicable organisational and project standards and policies
- be traceable back to project objectives and any business needs expressed in a business case
- cross-reference any other user stories that relate to the same feature, but for different users.
Resources
Use cases capture the user (actor) point of view while describing the functional requirements of the system. They describe the step-by-step process a user goes through to complete that goal using a software system.
A use case is a description of all the ways an end-user wants to ‘use’ a system. Use cases capture all the possible ways the user and system can interact that result in the user achieving their goal. They also capture all the things that can go wrong along the way that prevent the user from achieving the goal.
A use case model consists of several model elements. The most important model elements are:
- use cases
- actors
- and the relationships between them.
Are a user story and use case the same thing?
While user stories are centred on the result and the benefit of the thing it describes, use cases can be more granular and describe how a system should act.
A high-level use case is a summary of the task, written as unstructured text between one sentence and two paragraphs in length. Its purpose within an outcomes-focused challenge statement is to give just enough detail for suppliers to understand the use case scenario and complexity.
High level use cases are elaborated to include the current state situation, user stories, desired outcome, and measures of success.
The basic structure of a use case
There is no standard for use case structure or content. The important thing is to clearly capture the business process in a textual, narrative form.:
- name the use case
- use case level
- summarise the use case
- define the actor.
Actors
An actor is a role adopted by someone or something that interacts with the system that you have no control over. It can be a person or another software system.
For a given task, identify the people that perform that particular job. Here are some questions that can help you identify potential actors:
- who uses the data in the system?
- who maintains the data in the system?
- who needs to be notified when data changes?
- what other systems might use the system?
- what happens automatically?
Resources
Use cases can be written at several levels of detail. Each level refines the one above it.
- detailed use cases are not recommended for an innovation challenge statement
- detailed use cases are recommended for writing the scope for subsequent stages when the requirements are better understood, require more definition, and include constraints such as systems architecture and data.
- after suppliers have submitted an initial proposal responding to a high level use case in a challenge statement, subsequent proof stages or implementation at scale might ask suppliers to respond to more detailed use cases
In such cases, high level use cases may be elaborated to two subsequent levels of detail:
Business level use case
- the business level use case captures the business process (the ‘user view’) as a time-ordered sequence of steps
- it does not show the human/computer interactions - it is written as though the actors do all the work. It identifies the process (for application development) and domain objects (for data modelling)
- it is written in a meeting with the design team and a subject matter expert, and may take hours or a day or two to write clearly and with sufficient detail for data modelling.
Design Level use Case
- the design level use case captures the interaction between the actors and the system
- the writer must determine which steps in the use case are the responsibility of the system
- it is written as a dialog between the actors and the system writing a design-level use case is the beginning of application design, and may proceed through several iterations of refinement until it introduces interface controls.
Product use cases aren't strictly use cases. They are detailed specifications used to generate products.
Detailed use case structure
- the major structural difference between high level use cases and detailed types of use cases is in how the description is written
- buying teams should replace the summary from the high level use case with more detailed ‘scenarios’ that describe the typical path through the use case (the primary scenario), any alternate paths (secondary scenarios) and how errors are handled (exception scenarios)
- to ensure that the data modelling in a use case is accurate, it’s important to ensure all the important concepts required by the use case are mentioned.