Skip to content

Beginner · Planning an app · topic 5 of 34 · 25 min

Requirements and user stories

Explanation

Before writing code, write down what the app must do and for whom. A user story says who wants something, what they want and why. Acceptance criteria say when a story is done. You then pick the smallest useful set of stories, the MVP, and build that first.

Why plan before coding?

Many beginners open the editor and start typing. After two weeks they find the app does the wrong thing, or the database cannot hold what the screens need. A short plan saves days of rework.

Think of it like this: Nobody builds a house by laying bricks and deciding later where the kitchen goes. First there is a plan: how many rooms, where the doors are, where water and power come in. Changing a line on paper costs nothing. Moving a wall after it is built costs a lot. Planning an app works the same way.

A requirement is one thing the app must do or one rule it must follow. "Users can pin a note" is a requirement. "A note title is at most 100 characters" is also a requirement.

Start with the problem and the users

A problem statement is one or two sentences about the pain you are solving. For our Notes app: "Students keep study notes on paper and in chat messages, and lose them. They need one simple place to write, find and pin notes from any phone or laptop."

Users are the kinds of people who will use the app. Name them by role: student, teacher, admin. Each role may want different things.

User stories

A user story is one small need written from the user's side, in a fixed pattern: "As a <role>, I want <something>, so that <reason>." The reason matters: it tells you what problem the feature really solves.

output
As a student, I want to pin a note, so that my exam notes stay at the top.
As a student, I want to search my notes, so that I can find a formula in seconds.
As a student, I want to log in on any device, so that my notes are with me everywhere.
Three user stories for the Notes app.

Acceptance criteria are checks that say when a story is done. They are written so that anyone can test them, for example: "Given a pinned note, when I open my notes list, then the pinned note is shown first."

MVP and MoSCoW

MVP means Minimum Viable Product: the smallest version that is already useful to real users. MoSCoW is a simple way to sort stories into four groups so the MVP is clear.

GroupMeaningNotes app example
MustWithout it the app is uselessSign up, log in, create, edit, delete notes
ShouldImportant, but the app works without itPin a note, search notes
CouldNice to have if time allowsTags, dark mode
Won't (this time)Agreed to leave out for nowSharing notes with friends, images
Tip: Build all the Must stories first and ship them. Then add Should stories one by one. A small app that works beats a big app that is half finished.
Careful: Do not write stories about technology ("As a user, I want a PostgreSQL database"). Users do not care. Write what they need; the technology is your choice later.

The Notes app requirements (our plan for this course)

  • Must: a user can sign up with name, email and password, then log in and log out.
  • Must: a logged-in user can create, read, edit and delete only their own notes.
  • Must: a note title is required, 1 to 100 characters after trimming spaces; the body is up to 5000 characters.
  • Should: a user can pin a note; pinned notes show first, then newest first.
  • Should: a user can search notes by words in the title or body.
  • Could: tags on notes. Won't (for now): sharing notes with other users.

Watch the lesson

Requirements and user stories · 1/7

Plan first, code second

Before we write any code for our Notes app, we plan. Today we learn how to write requirements.

Prefer a video by a teacher? Find free videos on “user stories and acceptance criteria explained for beginners” on YouTube ↗

In real life: A college canteen pre-order app

A college wants students to pre-order lunch so the queue at 1 pm is shorter. The team writes the problem statement, then stories such as "As a student, I want to see today's menu with prices, so that I can choose before class ends" and "As canteen staff, I want a list of orders by pickup time, so that food is ready on time." Online payment is marked Could; paying cash at pickup is the MVP. The first version ships in two weeks instead of two months.

Practice (0/3 done)

Task 1 · Code · Javascript

Write a function isUserStory(text) that returns true when the text follows the pattern "As a <role>, I want <something>, so that <reason>" and false otherwise. Rules: ignore spaces at the start and end; accept "As a" or "As an"; the comma before "so that" is optional; ignore upper and lower case.

Task 2 · Code · Javascript

Each story is an object { text, priority } where priority is "must", "should", "could" or "wont". Write sortStories(stories) that returns a NEW array sorted must first, then should, then could, then wont. Stories with the same priority keep their original order. Do not change the input array.

Task 3 · Practice

Plan a college event booking app (students book seats for fests, workshops and talks). Write a problem statement, at least 6 user stories for two roles, acceptance criteria for one story, and sort all stories with MoSCoW.

Quick quiz

Question 1

1.Which of these is a correctly written user story?

Question 2

2.What does MVP mean?

Question 3

3.In MoSCoW, where does "share notes with friends" go if the team agrees to skip it for now?

Question 4

4.What are acceptance criteria for?

Question 5

5.Why does a user story include "so that <reason>"?

Pass the quiz (60% or more) or mark this topic as done when you are ready.

Your progress is saved on this device only.

Next: Designing the data model →

← Previous: Setting up your tools