CS2103/T - Admin: tP week 5: Gather requirements

Brainstorm user stories before the tutorial
Choose user stories for v1.2 before/during the tutorial

1 Brainstorm user stories before the tutorial

Learn the recipe for brainstorming user stories in the textbook → Specifying Requirements → UserStories → Usage.
Also learn about brainstorming and user stories.
Follow the steps in the recipe mentioned above to arrive at user stories for the the product, with your team members. If you didn't attend the lecture, please watch the lecture recording to learn more about this step.
How many user stories? Aim to collect more user stories than you can deliver in the project. Aim to create at least 30 user stories. Include all 'obvious' ones you can think of but also look for 'non obvious' ones that you think are likely to be missed by other competing products.
User stories of what size? Normally, it is fine to use epic-level user stories in the early stages of a project but given this is a small project, you may want to define smaller user stories (i.e., small enough for one person to implement in 1-2 days).
- Bad As a user, I can track my schedule, so that I can know when to do things.
  Reason: too big, as track can involve a lot of things.
- Good As a user, I can add a time to a task, so that I can record when a task need to be done.
- Good As a user, I can see the pending task that has the next earliest deadline, so that I can know what I need to do next.
What format?: You may use a sentence format or a table format but do maintain the prescribed three-part structure of a user story. In particular, try to include the benefit part in most user stories as that will come in handy when prioritizing user stories later.
How to record?
Keep records of intermediate steps (e.g., persona, scenarios) in your collaborative project document started in the previous week.
You can ~~write each user story in a piece of paper (e.g. yellow sticky note, index card, or just pieces of paper about the size of a playing card). Alternatively you can~~ use an online tool (some examples given in [Textbook Specifying Requirements → UserStories → Usage → (panel) Tool Examples ]).

Requirements → Specifying Requirements →

User stories

Introduction

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

You can write user stories on index cards or sticky notes, and arrange them on walls or tables, to facilitate planning and discussion. Alternatively, you 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 reuse 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 The number of leave days not yet takenleave 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.

Details

Can write more detailed user stories

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

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 did 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 extra

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 conﬁrmation of any cancelled reservation
[Epic] As a frequent ﬂyer, I want to book a trip
- As a frequent ﬂyer, I want to book a trip using miles
- As a frequent ﬂyer, I want to rebook a trip I take often
- As a frequent ﬂyer, I want to request an upgrade
- As a frequent ﬂyer, I want to see if my upgrade cleared

Choose the correct statements

a. User stories are short and written in a formal notation.
b. User stories is another name for use cases.
c. User stories describes past experiences users had with similar systems. These are helpful in developing the new system.
d. User stories are not detailed enough to tell us exact details of the product.

Explanation: User stories are short and written in natural language, NOT in a formal language. They are used for estimation and scheduling purposes but do not contain enough details to form a complete system specification.

Usage

Can use user stories to manage requirements of project

User stories capture user requirements in a way that is convenient for i.e. which features to include in the productscoping, i.e. how much effort each feature will takeestimation, and i.e. when to deliver each featurescheduling.

[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 e.g. a description of the requirements written in prosetraditional 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.

Requirements → Requirements →

Non-functional requirements

Requirements can be divided into two in the following way:

Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which the system is developed and operated.

Some examples of non-functional requirement categories:

Data requirements e.g. size, how often do data changevolatility, saving data permanentlypersistency etc.,
Environment requirements e.g. technical environment in which the system would operate in or needs 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.

You 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.

An example of an 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.

A recipe for brainstorming user stories

Given below is a possible recipe you can take when using user stories for early stages of requirement gathering.

Step 0: Clear your mind of preconceived product ideas

Even if you already have some idea of what your product will look/behave like in the end, clear your mind of those ideas. The product is the solution. At this point, we are still at the stage of figuring out the problem (i.e., user requirements). Let's try to get from the problem to the solution in a systematic way, one step at a time.

Step 1: Define the target user as a persona:

Decide your target user's profile (e.g. a student, office worker, programmer, salesperson) 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 narrow it down to a persona. Here is an example:

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

Step 2: Define the problem scope:

Decide the exact problem you are going to solve for the target user. It is also useful to specify what related problems it will not solve so that the exact scope is clear.

ProductX helps Jean keep track of all her school contacts. It does not cover communicating with contacts.

Step 3: List scenarios to form a narrative:

Think of the various scenarios your target user is likely to go through as she uses your app. Following a chronological sequence as if you are telling a story might be helpful.

A. First use:

Jean gets to know about ProductX. She downloads it and launches it to check out what it can do.

After playing around with the product for a bit, Jean wants to start using it for real.

...

B. Second use: (Jean is still a beginner)

Jean launches ProductX. She wants to find ...

...

C. 10th use: (Jean is a little bit familiar with the app)

...

D. 100th use: (Jean is an expert user)

Jean launches the app and does ... and ... followed by ... as per her usual habit.

Jean feels some of the data in the app are no longer needed. She wants to get rid of them to reduce clutter.

More examples that might apply to some products:

Jean uses the app at the start of the day to ...

Jean uses the app before going to sleep to ...

Jean hasn't used the app for a while because she was on a three-month training programme. She is now back at work and wants to resume her daily use of the app.

Jean moves to another company. Some of her clients come with her but some don't.

Jean starts freelancing in her spare time. She wants to keep her freelancing clients separate from her other clients.

Step 4: List the user stories to support the scenarios:

Based on the scenarios, decide on the user stories you need to support. For example, based on the scenario 'A. First use', you might have user stories such as these:

As a potential user exploring the app, I can see the app populated with sample data, so that I can easily see how the app will look like when it is in use.

As a user ready to start using the app, I can purge all current data, so that I can get rid of sample/experimental data I used for exploring the app.

To give another example, based on the scenario 'D. 100th use', you might have user stories such as these:

As an expert user, I can create shortcuts for tasks, so that I can save time on frequently performed tasks.

As a long-time user, I can archive/hide unused data, so that I am not distracted by irrelevant data.

Do not 'evaluate' the value of user stories while brainstorming. Reason: an important aspect of brainstorming is not judging the ideas generated.

Other tips:

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. That is, don't try to reverse-engineer a preconceived product idea into user stories.
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 e.g. index cards or sticky notesphysical paper in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not physically in the same locationco-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:

You can break the user story into issue subject and description in this way:

title	`As a user I can add a deadline`
Description	`... so that I can keep track of my deadlines`

Alternatively, you can put the entire user story in the description.

title	`Add deadline`
Description	`As a user I can so that I can keep track of my deadlines`

In both cases, apply the type.Story label.

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.

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:

You can break the user story into issue subject and description in this way:

title	`As a user I can add a deadline`
Description	`... so that I can keep track of my deadlines`

Alternatively, you can put the entire user story in the description.

title	`Add deadline`
Description	`As a user I can so that I can keep track of my deadlines`

In both cases, apply the type.Story label.

A video on GitHub Project Boards:

Example Google Sheet for recording user stories:

Example Trello Board for recording user stories:

If you choose to use the GitHub issue tracker to manage user stories, you need to set up your team's GitHub organization, team repo, and its issue tracker first. Instructions for doing those steps are in the panel below.

tP Team Organization Setup

Please follow the organization/repo name format precisely or else our grading scripts will not be able to detect your work.

(/) Only one team member:

After receiving your team ID, one team member should do the following steps:

Create a GitHub organization with the following details:
- Organization name (all UPPER CASE) : AY2021S1-TEAM_ID. e.g. AY2021S1-CS2103T-W12-1, AY2021S1-CS2103-T09-2
- Plan: Open Source ($0/month)
- This organization belongs to: My personal account
Add members to the organization:
- Create a team called developers to your organization.
- Add your team members to the developers team.

tP Team Repo Setup

(/) Only one team member:

Fork the https://github.com/nus-cs2103-AY2021S1/tp repo to your team org.
- This repo (let's call it the team repo) is to be used as the repo for your project.
- Please do not rename the fork Reason: our grading scripts rely on the repo name.
Enable the issue tracker.
Enable GitHub Actions: Go to the Actions tab and enable workflows by clicking the button. That will enable the GitHub Actions that are already included in the repo you forked.
Set up the project website
Follow instructions in the Documentation guide page of AB3 developer guide. When set up correctly, your project website should be available via the URL https://ay2021s1-{team-id}.github.io/tp e.g., https://ay2021s1-cs2103-w13-1.github.io/tp.
Add members. Ensure your team members have the desired level of access to your team repo.
Recommended: Give admin access to 1-2 members and write access to others.
Create a team PR for us to track your project progress: i.e., create a PR from your team repo master branch to [nus-cs2103-AY2021S1/tp] master branch. PR name: [Team ID] Product Name e.g., [CS2103-T09-2] Contact List Pro. As you merge code to your team repo's master branch, this PR will auto-update to reflect how much your team's product has progressed.
Please fill in these details as specified because they are used by our grading scripts.
- PR subject: the name of your product e.g., InsureList
- Description: a 1-2 sentence overview (plain text only, no formatting or links) of your project indicating the target user and the value proposition e.g., InsureList helps insurance agents manage detail of their clients. It is optimized for CLI users so that frequent tasks can be done faster by typing in commands.

tP Issue Tracker Setup

We recommend you configure the issue tracker of the tP team repo as follows:

Delete existing labels and add the following labels.
Issue type labels are useful from the beginning of the project. The other labels are needed only when you start implementing the features.

Issue type labels:

type.Epic : A big feature which can be broken down into smaller stories e.g. search
type.Story : A user story
type.Enhancement: An enhancement to an existing story
type.Task (or type.Chore) : Something that needs to be done, but not a story, bug, or an epic. e.g. Move testing code into a new folder)
type.Bug : A bug

Priority labels:

priority.High : Must do
priority.Medium : Nice to have
priority.Low : Unlikely to do

Bug Severity labels:

severity.VeryLow : A flaw that is purely cosmetic and does not affect usage e.g., a typo/spacing/layout/color/font issues in the docs or the UI that doesn't affect usage.
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.
severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.
severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.

When applying for documentation bugs, replace user with reader.

Create following milestones : v1.1, v1.2, v1.3, v1.4
You may configure other project settings as you wish. e.g. more labels, more milestones

2 Choose user stories for v1.2 before/during the tutorial

Project planning, with a twist

Intuitively, you might think the right thing to do is to decide what features will be in v1.4 and then plan the intermediate versions based on that. But that's not what we are going to do.

Why? Given the difficulty of reliably estimating the effort each feature will need, any such long-range plan is likely to be inaccurate.

Instead, what we will do is to assume the current iteration is the last iteration, plan that iteration to deliver the product (based on available time), and try to follow that plan as best as we can. After the iteration is over, we plan the next iteration as if it's the last iteration. But that time, you can factor in the experience from the previous iteration to do a better job of planning.

How is that better?

Shorter-term plans have a better chance of being accurate and doable.
You get multiple clean shots at project planning. Each try can learn from the previous tries. Hence, more learning.
As each iteration produces a working product, you always have a working product, which practically eliminates the risk failing to deliver a working product by the final deadline.

The goal of this activity is to come up with the smallest possible product that is still usable so that it can be implemented as v1.2, to be delivered at the end of the first project iteration. We try to make it small because you will have only two weeks to implement v1.2 and coding as a team is a lot harder than writing code alone.

Do not discuss features, UI, command format, or implementation details yet. That would be like putting the cart before the horse. At this stage we are simply trying to choose which user needs to fulfill first.

If the product can be of some use without a given user story, that user story should be left out of v1.2, even if the omission makes the product hard to use, as long as the product is not impossible to use e.g., in most cases a product can be used without an 'edit item' feature because the user can always delete an item and add a new item instead of editing an existing an item.
Don't worry about v1.3. You can design v1.3 after v1.2 done.
Don't worry about v1.2 being 'too small'. You can always add more features to v1.2 if you finish it ahead of schedule.
You can also select an additional set of user stories that are nice-to-have in v1.2, to be done but only if there's time left.
If possible, narrow the scope of v1.2 further e.g., narrower target user, a smaller value proposition.

Suggested workflow:

First stage:
- Divide the user stories among team members.
- Each member will go through their user stories to discard (e.g., cross out, or move to a different location, but not delete) which are definitely not needed for v1.2.
Second stage:
- All members discuss the remaining user stories (i.e., the ones not discarded in the first stage), and try to trim the list further.

tP week 5: Gather requirements