Software requirements

In a brainstorming session there are no "bad" ideas. The aim is to generate ideas; not to validate them. Brainstorming encourages you to "think outside the box" and put "crazy" ideas on the table without fear of rejection.

Carefully designed questionnaires can be used to solicit responses and opinions from a large number of users regarding any current system or a new innovation.

Observation of users in their natural work environment is commonly used to understand the tasks and the environment of the user. Interaction logging on an existing system can also be used to gather information about how an existing system is being used.

Interviewing potential stakeholders and domain experts can give us useful information about a domain, by getting users to explore what users feel about the required system. Interviews also provide opportunities for the development team members to meet stakeholders and to make stakeholders feel involved in the development process.

In a focus group, a group of people (e.g. potential users, beta testers) are asked about their understanding of a specific issue or a process. Focus groups can bring out undiscovered conflicts and misunderstandings among stakeholder interests which can then be resolved or clarified as necessary.

Early UI prototyping, i.e. sketching the user interface for the intended product, is a good technique to uncover requirements, in particular, those related to how users interact with the system. UI prototypes are often used in brainstorming sessions, or in meetings with the users to get quick feedback from them.

^{Simple text UI prototype for a primitive CLI (Command Line Interface) Minesweeper.}

^{Simple GUI prototype for the same Minesweeper, created using Powerpoint}

^{source: http://balsamiq.com/products/mockups}

Studying existing products can unearth shortcomings of existing solutions that can be addressed by a new product. For example, when developing a game for a mobile device, a look at a similar PC game can give insight into the kind of features and interactions the mobile game might offer. Product manuals and other forms of technical documentation of an existing system can be a good way to learn about how the existing solutions work.

A textual description (prose) can be used to give a quick overview of the domain/system that is understandable to both the users and the development team.

This is the most straight forward way of describing requirements, and is especially useful when describing the vision of a product.

Here is a sample feature list from Minesweeper (only a brief description has been provided to save space):

A common format for writing user stories is:

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 such as GitHub Project Boards 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]}

The {benefit} can be omitted if it is obvious.

We can add more characteristics to the {user role} to provide more context to the user story.

We can write user stories at various levels. High-level user stories, called epics (or themes) cover bigger functionality. We can then break down these epics to multiple user stories of normal size.

We 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’.

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

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. [🔖]

User stories can capture non-functional requirements too because even NFRs must benefit some stakeholder.

A use case describes an interaction between the user and the system for a specific functionality of the system.

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.

Use cases can be used to capture the functional requirements of a system.

A use case is an interaction between a system and its actors.

Actors in Use Cases

A use case can involve multiple actors.

An actor can be involved in many use cases.

A single person/system can play many roles.

Many persons/systems can play a single role.

{some guidance on identifying actors and use cases}

Use cases can be specified at various levels of detail.

Consider the three use cases given above for the LearnSys system. Clearly, (a) is at a higher level than (b) and (b) is at a higher level than (c).

{some guidance on using diagrams vs other means}

🏆 Able to use use cases to list functional requirements of a simple system

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.

...

Writing use case steps

Software System: Square game  
Use case:  UC02 - Play a Game
Actors: Player (multiple players)
        1. A Player starts the game.
        2. SquareGame asks for player names.
        3. Each Player enters his own name.
        4. SquareGame shows the order of play.
        5. SquareGame prompts for the current Player to throw die.
        6. Current Player adjusts the throw speed.
        7. Current Player triggers the die throw.
        8. Square Game shows the face value of the die.
        9. 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.
        10. Square Game shows the Winner.
        Use case ends.

Main success scenario

System: Online Banking System (OBS)
Use case: UC23 - Transfer Money
Actor: User
MSS:
	1. User chooses to transfer money.
	2. OBS requests for details of the transfer.
	3. User enters the requested details.
	4. OBS requests for confirmation.
	5. User confirms transfer.
	6. 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.

Extensions

Extensions, given below the MSS, are "add-on"s to the MSS. They are also called exceptional flow of events or 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. Note that the numbering style is not a rule but just a convention. The third extension, labeled 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.

<< extend >> relationship between use cases is used to capture extensions to the use cases. Note how the arrow is pointing the other way.

Inclusions

A use case can "include" another use case. Underlined text is commonly used to show an inclusion of a use case. 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.

Use case preconditions

Software System: Online Banking System
Use case: UC23 - Transfer Money
Actor: User
Preconditions: User is logged in.
MSS:
	1. User chooses to transfer money.
	2. OBS requests for details for the transfer.
	 ...

Use case guarantees

Software System: Online Banking System
Use case: UC23 - Transfer Money
Actor: User
Preconditions: User is logged in.
Guarantees:
       * Money will be transferred to the destination account.
       * All steps of the transaction will be logged.
MSS:
	1. User chooses to transfer money.
	2. OBS requests for details for the transfer.
	 ...

System: EZ-Link machine (those found at MRTs)
Use case: UC2 top-up EZ-Link card
Actor: EZ-Link card user

System: EZ-Link machine (those found at MRTs)
Use case: UC2 top-up EZ-Link card
Actor: EZ-Link card user
Preconditions: All hardware in working order.
Guarantees:  MSS -> the card will be topped-up.
MSS:
	1. User places the card on the reader.
	2. System displays card details and prompts for desired action.
	3. User selects top-up.
	4. System requests for top-up details (amount, payment option, receipt required?).
	5. User enters details.
	6. System processes cash payment (UC02) or NETS payment (UC03).
	7. System updates the card value.
	8. System indicates transaction as completed.
	9. If requested in step 5, system prints receipt.
	10. User removes the card.
         Use case ends.

Extensions:
	*a. User removed card or other hardware error detected.
	*a1. System indicates the transaction has been aborted.
         Use case ends.

System: EZ-Link machine
Use case:  UC03 process NETS payment
Actor: EZ-Link card user
Preconditions: A transaction requiring payment is underway.
Guarantees: MSS → Transaction amount is transferred from user account to EZ-Link company account.
MSS:
	1. System requests to insert ATM card.
	2. User inserts the ATM card.
	3. System requests for PIN.
	4. User enters PIN.
	5. System reports success.
         Use case ends.

Extensions:
	2a. Unacceptable ATM card (damaged or inserted wrong side up).
         …
	4a. Wrong PIN.
         …
	4b. Insufficient funds.
         …
	*a. Connection to the NETS gateway is disrupted.
         …

System: LearnSys
Use case: UC01 reply to post in the forum
Actor: Student

System: LearnSys
Use case: UC01 reply to post in the forum
Actor: Student
Preconditions: Student is logged in and has permission to post in the forum. The post to which the Student replies already exists.
Guarantees: * MSS -> post will be added to the forum.
MSS:
	1. Student chooses to reply to an existing post.
	2. LearnSys requests the user to enter post details.
	3. Student enters post details.
	4. Student submits the post.
	5. LearnSys displays the post.
         Use case ends.

Extensions:
	*a. Internet connection goes down.
         …
	*b. LearnSys times out.
         …
	3a. Student chooses to ‘preview’ the post.
  	  	3a1. LearnSys shows a preview.
  	  	3a2. User chooses to go back to editing.
  	  	Use case resumes at step 3.
	3b. Student chooses to attach picture/file
         …
	3c. Student chooses to save the post as a draft.
      	       3c1. LearnSys confirms draft has been saved.
      	       Use case ends.
	3d. Student chooses to abort the operation.
         …
	4a. The post being replied to is deleted by the owner while the reply is being entered.
         …
	4b. Unacceptable data entered.
         …

More on use case diagrams

Actor generalization

Do not over-complicate use case diagrams.

System as an actor

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. For example, 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.

More on use case descriptions

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.

Pros and cons

Here are some of the advantages of documenting system requirements as use cases:

• Since 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.

As an example, here is a partial glossary from a variant of the Snakes and Ladders game:

A supplementary requirements section contains elements which do not fit elsewhere.

Examples of of requirements typically found under this heading include: