Why a vague sentence cannot be built
A requirement is a statement of what a system must do, or how well it must do it. Clear requirements matter because a team can only build and test what it has understood.
A lecturer asks for a room booking system that is "fast and easy". Nobody can build or test that. This lesson turns needs like it into requirements you can check.
By the end of this lesson
Note
I can turn a need into a requirement that can be tested.
Key words
| Word | What it means | Example |
|---|---|---|
| Need | a problem a person wants solved | |
| Requirement | a statement of what the system must do or be | The system shall refuse a double booking. |
| Stakeholder | anyone who uses the system or is affected by it | |
| Testable | two people can check it and agree on pass or fail | |
| Functional requirement | says what the system does | |
| Non-functional requirement | says how well the system does it |
The cells students fill in are left blank in this preview.
Needs are problems, requirements are promises
A need is what a person wants to be able to do. A requirement is a statement the finished system must meet. People talk in needs. A team builds from requirements.
To get from one to the other, ask three things. Who has the need? What do they do? How will we know it works? Many teams write a requirement with the word "shall", for example "The system shall list every booking for a room."
Worked example: from needs to requirements
| Need | Stakeholder | Requirement |
|---|---|---|
| I never know which room is free | Lecturer | The system shall list every booking for a room on a given day. |
| Students keep taking my slot | Lecturer | The system shall refuse a second booking of the same room and slot. |
| I want to cancel without ringing anyone | Student | A person shall be able to cancel their own booking. |
The cells students fill in are left blank in this preview.
Start from a real system to specify
The lab holds a small web API over a database. You will treat it as the system whose requirements you write.
First give the terminal the database password. Then one command makes a bookings table with three bookings and tells the API to look at it. Last, read the table back as JSON.
Give psql the password
export PGPASSWORD=shopShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Make the bookings table
psql -h db -U shop -c "drop table if exists bookings; create table bookings (id serial primary key, room text not null, slot text not null, booked_by text not null, hours int not null, status text not null default 'booked'); insert into bookings (room, slot, booked_by, hours) values ('Lab 2', 'Mon 10:00', 'Asha', 2), ('Lab 4', 'Mon 10:00', 'Ben', 1), ('Lab 2', 'Tue 14:00', 'Asha', 3); notify pgrst, 'reload schema'"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Read all the bookings
curl -s -w "\n" "http://api:3000/bookings?order=id"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A testable requirement has no vague words
A requirement is testable when two people can run the same check and agree on pass or fail. Words like fast, easy and many are vague, because each reader pictures a different number.
Replace the vague word with a number, a limit or an action someone can see.
Worked example: vague into testable
| Vague | Why it fails | Testable |
|---|---|---|
| The list loads fast | Fast for whom? | The list of bookings answers within 2 seconds. |
| The system is easy to use | Easy for whom? | A new student books a room in 5 clicks or fewer. |
| Many people can book at once | How many is many? | 50 people can book at the same time with no error. |
The cells students fill in are left blank in this preview.
A common mistake
Warning
Many people think a requirement is good when it sounds professional. "The system shall be user-friendly" sounds fine, but it can never fail, so it cannot be tested. Ask what you would measure to say it had failed.
Missing requirements show up when you probe
Some requirements are missing because nobody thought to ask. Try the system with input a careless user might send.
The first Run books Lab 2 for minus 5 hours. The second leaves the room out. Each prints only the status code.
Book a room for minus 5 hours
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"room":"Lab 2","slot":"Wed 9:00","booked_by":"Chen","hours":-5}' "http://api:3000/bookings"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Book with no room named
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"slot":"Wed 9:00","booked_by":"Chen","hours":1}' "http://api:3000/bookings"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Each surprise becomes a requirement
The first Run prints 201. The API accepted minus 5 hours, so a requirement is missing. Write it: "The system shall refuse a booking of fewer than 1 hour." That is a functional requirement, because it says what the system does.
The second prints 400. The database already refuses a booking with no room, so write it down: "The system shall refuse a booking with no room."
A non-functional requirement says how well, such as "The list answers within 2 seconds."