Specifying Requirements

Prose

Can explain prose

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

Can explain feature list

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

Can write simple user stories

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.

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

a. They are based on stories users tell about similar systems
b. They are written from the user/customer perspective
c. They are always written in some physical medium such as index cards or sticky notes

a. Reason: Despite the name, user stories are not related to 'stories' about the software.
b.
c. Reason: It is possible to use software to record user stories. When the team members are not co-located this may be the only option.

Critique the following user story taken from a software project to build an e-commerce website.

As a developer, I want to use Python to implement the software, so that we can resue existing Python modules.

Refer to the definition of a user story.

This user story is not written from the perspective of the user/customer.

Bill wants you to build a Human Resource Management (HRM) system. He mentions that the system will help employees to view their own leave balance. What are the user stories you can extract from that statement?

Remember to follow the correct format when writing user stories.

User story format: As a {user type/role} I can {function} so that {benefit}

As an employee, I can view my leave balance, so that I can know how many leave days I have left.

Note: the {benefit} part may vary as it is not specifically mentioned in the question.

Can use user stories to manage requirements of project

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.

Example Project Board:

Example Issue to represent a user story:

A video on GitHub Project Boards:

Example Google Sheet for recording user stories:

Example Trello Board for recording user stories:

This article by Mike Cohn from MountainGoatSoftware explains how to use user stories to capture NFRs.

Use Cases

Can explain use cases

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
1. User inserts an ATM card
2. ATM prompts for PIN
3. User enters PIN
4. ATM prompts for withdrawal amount
5. User enters the amount
6. ATM ejects the ATM card and issues cash
7. User collects the card and the cash.

System: A Learning Management System (LMS)
Actor: Student
Use Case: Upload file
1. Student requests to upload file
2. LMS requests for the file location
3. Student specifies the file location
4. 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.

Use cases capture the functional requirements of a system.

Can use use cases to list functional requirements of a simple system

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

Actors: Guest, Student, Staff, Admin, ExamSys, LibSys.

A use case can involve multiple actors.

Software System: LearnSys
Use case: UC01 conduct survey
Actors: Staff, Student

An actor can be involved in many use cases.

Software System: LearnSys
Actor: Staff
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.

Consider a simple movie ticket vending machine application. Every week, the theatre staff will enter the weekly schedule as well as ticket price for each show. A customer sees the schedule and the ticket price displayed at the machine. There is a slot to insert money, a keypad to enter a code for a movie, a code for the show time, and the number of tickets. A display shows the customer's balance inside the machine. A customer may choose to cancel a transaction before pressing the “buy” button. Printed tickets can be collected from a slot at the bottom of the machine. The machine also displays messages such as "Please enter more money”, “Request fewer tickets" or "SOLD OUT!”. Finally, a "Return Change" button allows the customer to get back his unspent money.

Draw a use case diagram for the above requirements.

Note that most of the details in the description are better given as part of the use case description rather than as low-level use cases in the diagram.

A software house wishes to automate its Quality Assurance division.

The system is to be used by Testers, Programmers and System Administrators. Only an administrator can create new users and assign tasks to programmers. Any tester can create a bug report, as well as set the status of a bug report as ‘closed’. Only a programmer can set the state of a bug report to ‘fixed’, but a programmer cannot set the status of a bug report to ‘closed’. Each tester is assigned just one task at a time. A task involves testing of a particular component for a particular customer. Tester must document the bugs they find. Each bug is given a unique identifier. Other information recorded about the bug is component id, severity, date and time reported, programmer who is assigned to fix it, date fixed, date retested and date closed. The system keeps track of which bugs are assigned to which programmer at any given time. It should be able to generate reports on the number of bugs found, fixed and closed e.g. number of bugs per component and per customer; number of bugs found by a particular tester ; number of bugs awaiting to be fixed; number of bugs awaiting to be retested; number of bugs awaiting to be assigned to programmers etc.

Develop a use case diagram to capture their requirements given below.

Explanation: The given description contains information not relevant to use case modeling. Furthermore, the description is not enough to complete the use case diagram All these are realities of real projects. However, the process of trying to create this use case diagram prompts us to investigate issues such as:

Is ‘edit bug report’ a use case or editing the bug report is covered by other use cases such as those for setting the status of bug reports? If it is indeed a separate use case, who are the actors of that use case?
Does ‘assign task’ simply means ‘assign bug report’ or is there any other type of tasks?
There was some mention about Customers and Components. Does the system have to support use cases for creating and maintaining details about those entities? For example, should we have a ‘create customer record’ use case?
Which actors can perform the ‘generate report’ use case? Are reports generated automatically by the system at a specific time or generated ‘on demand’ when users request to view them? Do we have to treat different types of reports as different use cases (in case some types of reports are restricted to some types of users)? The above diagram assumes (just for illustration) that the report is generated on demand and only the system admin can generate any report.

Can optimize the use of use cases

You can use actor generalization in use case diagrams using a symbol similar to that of UML notation for inheritance.

In this example, actor Blogger can do all the use cases the actor Guest can do, as a result of the actor generalization relationship given in the diagram.

💡 Do not over-complicate use case diagrams by trying to include everything possible. A use case diagram is a brief summary of the use cases that is used as a starting point. Details of the use cases can be given in the use case descriptions.

Some include ‘System’ as an actor to indicate that something is done by the system itself without being initiated by a user or an external system.

The diagram below can be used to indicate that the system generates daily reports at midnight.

However, others argue that only use cases providing value to an external user/system should be shown in the use case diagram. For example, they argue that ‘view daily report’ should be the use case and generate daily report is not to be shown in the use case diagram because it is simply something the system has to do to support the view daily report use case.

We recommend that you follow the latter view (i.e. not to use System as a user). Limit use cases for modeling behaviors that involve an external actor.

UML is not very specific about the text contents of a use case. Hence, there are many styles for writing use cases. For example, the steps can be written as a continuous paragraph. Use cases should be easy to read. Note that there is no strict rule about writing all details of all steps or a need to use all the elements of a use case.

There are some advantages of documenting system requirements as use cases:

Because they use a simple notation and plain English descriptions, they are easy for users to understand and give feedback.
They decouple user intention from mechanism (note that use cases should not include UI-specific details), allowing the system designers more freedom to optimize how a functionality is provided to a user.
Identifying all possible extensions encourages us to consider all situations that a software product might face during its operation.
Separating typical scenarios from special cases encourages us to optimize the typical scenarios.

One of the main disadvantages of use cases is that they are not good for capturing requirements that does not involve a user interacting with the system. Hence, they should not be used as the sole means to specify requirements.

What are the advantages of using use cases (the textual form) for requirements modelling?

a. They can be fairly detailed but still natural enough for users for users to understand and give feedback.
b. The UI-independent nature of use case specification allows the system designers more freedom to decide how a functionality is provided to a user.
c. Extensions encourage us to consider all situations a software product might face during its operations.
d. They encourage us to identify and optimize the typical scenario of usage over exceptional usage scenarios.

(a) (b) (c) (d)

Which of these are correct?

a. Use case are not very suitable for capturing non-functional requirements.
b. Use case diagrams are less detailed than textual use cases.
c. Use cases are better than user stories.
d. Use cases can be expressed at different levels of abstraction.

(a)(b)(d)

Explanation: It is not correct to say one format is better than the other. It depends on the context.

Glossary

Can explain glossary

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

Can explain supplementary requirements

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.