This is a printer-friendly version. It omits exercises, optional topics (i.e., four-star topics), and other extra content such as learning outcomes.
Prose
What
A textual description (i.e. prose) can be used to describe requirements. Prose is especially useful when describing abstract ideas such as the vision of a product.
The product vision of the TEAMMATES Project given below is described using prose.
TEAMMATES aims to become the biggest student project in the world (biggest here refers to 'many contributors, many users, large code base, evolving over a long period'). Furthermore, it aims to serve as a training
tool for Software Engineering students who want to learn SE skills in the context of a non-trivial real software product.
Avoid using lengthy prose to describe requirements; they can be hard to follow.
Feature Lists
What
Feature List: A list of features of a product grouped according to some criteria such as aspect, priority, order of delivery, etc.
A sample feature list from a simple Minesweeper game (only a brief description has been provided to save space):
Basic play – Single player play.
Difficulty levels
Medium-levels
Advanced levels
Versus play – Two players can play against each other.
Timer – Additional fixed time restriction on the player.
...
User Stories
Introduction
User story: User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. [Mike Cohn]
A common format for writing user stories is:
User story format: As a {user type/role} I can {function} so that {benefit}
Examples (from a Learning Management System):
As a student, I can download files uploaded by lecturers, so that I can get my own copy of the files
As a lecturer, I can create discussion forums, so that students can discuss things online
As a tutor, I can print attendance sheets, so that I can take attendance during the class
We can write user stories on index cards or sticky notes, and arrange on walls or tables, to facilitate planning and discussion. Alternatively, we can use a software (e.g., GitHub Project Boards,
Trello, Google Docs, ...) to manage user stories digitally.
As a user, I can login to the system so that I can access my data
💡 It is recommended to confirm there is a concrete benefit even if you omit it from the user story. If not, you could end up adding features that have no real benefit.
You can add more characteristics to the {user role} to provide more context to the user story.
As a forgetful user, I can view a password hint, so that I can recall my password.
As an expert user, I can tweak the underlying formatting tags of the document, so that I can format the document exactly as I need.
You can write user stories at various levels. High-level user stories, called epics (or themes) cover bigger functionality. You can then break down these epics to multiple user stories of normal
size.
[Epic] As a lecturer, I can monitor student participation levels
As a lecturer, I can view the forum post count of each student so that I can identify the activity level of students in the forum
As a lecturer, I can view webcast view records of each student so that I can identify the students who did not view webcasts
As a lecturer, I can view file download statistics of each student so that I can identify the students who do not download lecture materials
You can add conditions of satisfaction to a user story to specify things that need to be true for the user story implementation to be accepted as ‘done’.
As a lecturer, I can view the forum post count of each student so that I can identify the activity level of students in the forum.
Conditions:
Separate post count for each forum should be shown
Total post count of a student should be shown
The list should be sortable by student name and post count
Other useful info that can be added to a user story includes (but not limited to)
Priority: how important the user story is
Size: the estimated effort to implement the user story
Urgency: how soon the feature is needed
More examples tangential
User stories for a travel website (credit: Mike Cohen)
As a registered user, I am required to log in so that I can access the system
As a forgetful user, I can request a password reminder so that I can log in if I forget mine
[Epic] As a user, I can cancel a reservation
As a premium site member, I can cancel a reservation up to the last minute
As a non-premium member, I can cancel up to 24 hours in advance
As a member, I am emailed a confirmation of any cancelled reservation
[Epic] As a frequent flyer, I want to book a trip
As a frequent flyer, I want to book a trip using miles
As a frequent flyer, I want to rebook a trip I take often
As a frequent flyer, I want to request an upgrade
As a frequent flyer, I want to see if my upgrade cleared
Usage
User stories capture user requirements in a way that is convenient for scoping, estimation and scheduling.
[User stories] strongly shift the focus from writing about features to discussing them. In fact, these discussions are more important than whatever text is written. [Mike Cohn, MountainGoat Software 🔗]
User stories differ from traditional requirements specifications mainly in the level of detail. User stories should only provide enough details
to make a reasonably low risk estimate of how long the user story will take to implement. When the time comes to implement the user story, the developers will meet with the customer face-to-face to work out a more detailed description of the
requirements. [more...]
User stories can capture non-functional requirements too because even NFRs must benefit some stakeholder.
An example of a NFR captured as a user story:
As a
I want to
so that
impatient user
to be able experience reasonable response time from the website while up to 1000 concurrent users are using it
I can use the app even when the traffic is at the maximum expected level
Given their lightweight nature, user stories are quite handy for recording requirements during early stages of requirements gathering.
💡 Here are some tips for using user stories for early stages of requirement gathering:
Define the target user: Decide your target user's profile (e.g. a student, office worker, programmer, sales person) and work patterns (e.g. Does he work in groups or alone? Does he share his computer with
others?). A clear understanding of the target user will help when deciding the importance of a user story. You can even give this user a name. e.g. Target user Jean is a university student studying in a non-IT field. She interacts with a lot of people due to her involvement in university clubs/societies. ...
Define the problem scope: Decide that exact problem you are going to solve for the target user. e.g. Help Jean keep track of all her school contacts
Don't be too hasty to discard 'unusual' user stories: Those might make your product unique and stand out from the rest, at least for the target users.
Don't go into too much details: For example, consider this user story: As a user, I want to see a list of tasks that needs my attention most at the present time, so that I pay attention to them first. When discussing this user story, don't worry about what tasks should be considered needs my attention most at the present time. Those details can be worked out later.
Don't be biased by preconceived product ideas: When you are at the stage of identifying user needs, clear your mind of ideas you have about what your end product will look like.
Don't discuss implementation details or whether you are actually going to implement it: When gathering requirements, your decision is whether the user's need is important enough for you to want to fulfil it. Implementation
details can be discussed later. If a user story turns out to be too difficult to implement later, you can always omit it from the implementation plan.
While use cases can be recorded on
physical paper in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not
co-located.
You can create issues for each of the user stories and use a GitHub Project Board to sort them into categories.
Extreme programming (XP) is a software development methodology which is intended to improve software quality and responsiveness to changing customer requirements. As a type of agile software development, it advocates frequent "releases" in short development cycles, which is intended to improve productivity and introduce checkpoints at which new customer requirements can be adopted. [wikipedia, 2017.05.01]
uses User stories to capture requirements.
This page in their website explains the difference between user stories and traditional requirements.
One of the biggest misunderstandings with user stories is how they differ from traditional requirements specifications. The biggest difference is in the level of detail. User stories should only provide enough detail to make a reasonably
low risk estimate of how long the story will take to implement. When the time comes to implement the story developers will go to the customer and receive a detailed description of the requirements face to face.
Use Cases
Introduction
Use Case: A description of a set of sequences of actions, including variants, that a system performs to yield an observable result of value to an
actor.[ 📖 :
uml-user-guideThe Unified Modeling Language User Guide, 2e, G Booch, J Rumbaugh, and I Jacobson ]
Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.
A use case describes an interaction between the user and the system for a specific functionality of the system.
System:
ATM
Actor: Customer
Use Case: Check account balance
User inserts an ATM card
ATM prompts for PIN
User enters PIN
ATM prompts for withdrawal amount
User enters the amount
ATM ejects the ATM card and issues cash
User collects the card and the cash.
System: A Learning Management System (LMS)
Actor: Student
Use Case: Upload file
Student requests to upload file
LMS requests for the file location
Student specifies the file location
LMS uploads the file
UML includes a diagram type called use case diagrams that can illustrate use cases of a system visually, providing a visual ‘table of contents’ of the use cases of a system.
In the example below, note how use cases are shown as ovals and user roles relevant to each use case are shown as stick figures connected to the corresponding ovals.
Unified Modeling Language (UML) is a graphical notation to describe various aspects of a software system. UML is the brainchild of three software modeling specialists James Rumbaugh,
Grady Booch and Ivar Jacobson (also known as the Three Amigos). Each of them has developed their own notation for modeling software systems before joining force to create a unified modeling language (hence, the term ‘Unified’ in UML).
UML is currently the de facto modeling notation used in the software industry.
Use cases capture the functional requirements of a system.
Identifying
A use case is an interaction between a system and its actors.
Actors in Use Cases
Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.
Some example actors for a Learning Management System
Use cases: UC01 conduct survey, UC02 Set Up Course Schedule, UC03 Email Class, ...
A single person/system can play many roles.
Software System: LearnSys
Person: a student
Actors (or Roles): Student, Guest, Tutor
Many persons/systems can play a single role.
Software System: LearnSys
Actor(or role) : Student
Persons that can play this role : undergraduate student, graduate student, a staff member doing a part-time course, exchange student
Use cases can be specified at various levels of detail.
Consider the three use cases given below. Clearly, (a) is at a higher level than (b) and (b) is at a higher level than (c).
System: LearnSys
Use cases: a. Conduct a survey b. Take the survey c. Answer survey question
💡 While modeling user-system interactions,
Start with high level use cases and progressively work toward lower level use cases.
Be mindful at which level of details you are working on and not to mix use cases of different levels.
Details
Writing use case steps
The main body of the use case is the sequence of steps that describes the interaction between the system and the actors. Each step is given as a simple statement describing who does what.
An example of the main body of a use case.
Student requests to upload file
LMS requests for the file location
Student specifies the file location
LMS uploads the file
A use case describes only the externally visible behavior, not internal details, of a system i.e. should not mention give details that are not part of the interaction between the user and the system.
This example use case step refers to behaviors not externally visible .
LMS saves the file into the cache and indicates success.
A step gives the intention of the actor (not the mechanics). That means UI details are usually omitted. The idea is to leave as much flexibility to the UI designer as possible. That is, the use case specification should be
as general as possible (less specific) about the UI.
The first example below is not a good use case step because contains UI-specific details. The second one is better because it omits UI-specific details.
Bad
: User right-clicks the text box and chooses ‘clear’
Good
: User clears the input
A use case description can show loops too.
An example of how you can show a loop:
Software System: Square game Use case:
UC02 - Play a Game Actors: Player (multiple players)
A Player starts the game.
SquareGame asks for player names.
Each Player enters his own name.
SquareGame shows the order of play.
SquareGame prompts for the current Player to throw die.
Current Player adjusts the throw speed.
Current Player triggers the die throw.
Square Game shows the face value of the die.
Square Game moves the Player's piece accordingly.
Steps 5-9 are repeated for each Player, and for as many rounds as required until a Player reaches the 100th square.
Square Game shows the Winner.
Use case ends.
The Main Success Scenario (MSS) describes the most straightforward interaction for a given use case, which assumes that nothing goes wrong. This is also called the Basic Course of Action or the
Main Flow of Events of a use case.
System: Online Banking System (OBS)
Use case: UC23 - Transfer Money
Actor: User
MSS:
User chooses to transfer money.
OBS requests for details of the transfer.
User enters the requested details.
OBS requests for confirmation.
OBS transfers the money and displays the new account balance.
Use case ends.
Note how the MSS assumes that all entered details are correct and ignores problems such as timeouts, network outages etc. Fro example, MSS does not tell us what happens if the user enters an incorrect data.
Extensions are "add-on"s to the MSS that describe exceptional/alternative flow of events. They describe variations of the scenario that can happen if certain things are not as expected
by the MSS. Extensions appear below the MSS.
This example adds some extensions to the use case in the previous example.
System: Online Banking System (OBS)
Use case: UC23 - Transfer Money
Actor: User
MSS:
User chooses to transfer money.
OBS requests for details of the transfer.
User enters the requested details.
OBS requests for confirmation.
OBS transfers the money and displays the new account balance.
Use case ends.
Extensions:
3a. OBS detects an error in the entered data.
3a1. OBS requests for the correct data.
3a2. User enters new data.
Steps 3a1-3a2 are repeated until the data entered are correct.
Use case resumes from step 4.
3b. User requests to effect the transfer in a future date.
3b1. OBS requests for confirmation.
3b2. User confirms future transfer.
Use case ends.
*a. At any time, User chooses to cancel the transfer.
*a1. OBS requests to confirm the cancellation.
*a2. User confirms the cancellation.
Use case ends.
*b. At any time, 120 seconds lapse without any input from the User.
*b1. OBS cancels the transfer.
*b2. OBS informs the User of the cancellation.
Use case ends.
Note that the numbering style is not a universal rule but a widely used convention. Based on that convention,
either of the extensions marked 3a. and 3b. can happen just after step 3 of the MSS.
the extension marked as *a. can happen at any step (hence, the *).
When separating extensions from the MSS, keep in mind that the MSS should be self-contained. That is, the MSS should give us a complete usage scenario.
Also note that it is not useful to mention events such as power failures or system crashes as extensions because the system cannot function beyond such catastrophic failures.
In use case diagrams you can use the <<extend>> arrows to show extensions. Note the direction of the arrow is from the extension to the use case it extends and the arrow uses a dashed line.
A use case can include another use case. Underlined text is commonly used to show an inclusion of a use case.
This use case includes two other use cases, one in step 1 and one in step 2.
Software System: LearnSys
Use case: UC01 - Conduct Survey
Actors: Staff, Student
MSS:
Staff creates the survey (UC44).
Student completes the survey (UC50).
Staff views the survey results. Use case ends.
Inclusions are useful,
when you don't want to clutter a use case with too many low-level steps.
when a set of steps is repeated in multiple use cases.
We use a dotted arrow and a <<include>> annotation to show use case inclusions in a use case diagram. Note how the arrow direction is different from the <<extend>> arrows.
Preconditions specify the specific state we expect the system to be in before the use case starts.
Software System: Online Banking System
Use case: UC23 - Transfer Money
Actor: User
Preconditions: User is logged in.
MSS:
User chooses to transfer money.
OBS requests for details for the transfer.
...
Guarantees specify what the use case promises to give us at the end of its operation.
Software System: Online Banking System
Use case: UC23 - Transfer Money
Actor: User
Preconditions: User is logged in.
Guarantees:
Money will be deducted from the source account only if the transfer to the destination account is successful
The transfer will not result in the account balance going below the minimum balance required.
MSS:
User chooses to transfer money.
OBS requests for details for the transfer.
...
Glossary
What
Glossary: A glossary serves to ensure that all stakeholders have a common understanding of the noteworthy terms, abbreviation, acronyms etc.
Here is a partial glossary from a variant of the Snakes and Ladders game:
Conditional square: A square that specifies a specific face value which a player has to throw before his/her piece can leave the square.
Normal square: a normal square does not have any conditions, snakes, or ladders in it.
Supplementary Requirements
What
A supplementary requirements section can be used to capture requirements that do not fit elsewhere. Typically, this is where most
Non Functional Requirements will be listed.
Requirements → Requirements →
Non-Functional Requirements
There are two kinds of requirements:
Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which system is developed and operated.
Some examples of non-functional requirement categories:
Data requirements e.g. size,
volatility,
persistency etc.,
Environment requirements e.g. technical environment in which system would operate or need to be compatible with.
Accessibility, Capacity, Compliance with regulations, Documentation, Disaster recovery, Efficiency, Extensibility, Fault tolerance, Interoperability, Maintainability, Privacy, Portability, Quality, Reliability, Response time, Robustness,
Scalability, Security, Stability, Testability, and more ...
Business/domain rules: e.g. the size of the minefield cannot be smaller than five.
Constraints: e.g. the system should be backward compatible with data produced by earlier versions of the system; system testers are available only during the last month of the project; the total project cost should not exceed
$1.5 million.
Technical requirements: e.g. the system should work on both 32-bit and 64-bit environments.
Performance requirements: e.g. the system should respond within two seconds.
Quality requirements: e.g. the system should be usable by a novice who has never carried out an online purchase.
Process requirements: e.g. the project is expected to adhere to a schedule that delivers a feature set every one month.
Notes about project scope: e.g. the product is not required to handle the printing of reports.
Any other noteworthy points: e.g. the game should not use images deemed offensive to those injured in real mine clearing activities.
We may have to spend an extra effort in digging NFRs out as early as possible because,
NFRs are easier to miss e.g., stakeholders tend to think of functional requirements first
sometimes NFRs are critical to the success of the software. E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.
Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?
a. The response to any use action should become visible within 5 seconds.
b. The application admin should be able to view a log of user activities.
c. The source code should be open source.
d. A course should be able to have up to 2000 students.
e. As a student user, I can view details of my team members so that I can know who they are.
f. The user interface should be intuitive enough for users who are not IT-savvy.
g. The product is offered as a free online service.
(a)(c)(d)(f)(g)
Explanation: (b) are (e) are functions available for a specific user types. Therefore, they are functional requirements. (a), (c), (d), (f) and (g) are either constraints on functionality or constraints on how the project
is done, both of which are considered non-functional requirements.
