JAVA-290 · Lesson 2 of 12 · 38 min
Requirements and user stories
▶ Video coming soon A video version of this lesson is on the way.
The kickoff had produced a direction: a booking website for repair customers. It had not produced requirements, and the team knew that the clients' first descriptions were only a starting point. Odile Branscombe knew what the shop needed, but she was not a customer who books repairs at lunch on a phone; Tamsin Rhee knew what mechanics need to know about a bike, but not what a customer finds confusing about a form. So before writing a single story, the team went to watch.
Watching before writing
On Saturday, May 13, 2028, Noemi Petrosyan and Thierry Dumont spent the morning beside the counter while Hamza did his usual volunteer shift. Noemi had learned the technique in her web courses as contextual inquiry: observing people doing the real task in the real place, and asking short questions at natural pauses, rather than asking them in a meeting what they would like. People are poor at predicting what they will want from software they have never seen, but they are reliable witnesses of what they do now and what annoys them about it.
They watched nine phone bookings and talked to six customers at the counter, each time asking first whether the customer minded a few questions about booking repairs; they wrote down what people said, not their names. Thierry kept the notes in a plain file, one observation per line, and on the Tuesday, May 16, he and Hamza did the same during Tamsin's repair night, where the volunteers who would fix the bikes explained what they wish customers told them.
| Observation | Source | What it suggests |
|---|---|---|
| Three callers asked for "the earliest time this week" | Phone, Saturday | Show the next free times first, not a calendar of a month |
| A caller spelled her phone number twice because Kofi misheard it | Phone, Saturday | Let customers type their own number, and check its form |
| "It makes a clicking noise" was the whole problem description for two bikes | Repair night | Offer a short list of problem kinds plus a free note |
| A customer asked whether she could cancel by text | Counter | Customers need a way to cancel without phoning |
| Two customers did not know a booking holds one start time for one bike | Counter | Say on the page what a booking includes |
| A volunteer wrote a booking on a sticky note because the counter computer was busy | Counter | Staff need a simple view of the day that is always current |
| An older customer preferred to phone and said websites "move too much" | Counter | Calm pages; the phone stays; no timers or animations |
| Tamsin checks each morning which bikes need parts that might be out | Repair night | Warn about out-of-stock parts when a problem kind usually needs one |
The draft personas from the kickoff survived with corrections. Dana the commuter was real, several times over. Marcus the parent appeared as a grandmother booking three bikes for grandchildren, so the team made the persona about the situation, several bikes, rather than the family role. And Rosa's preference for the phone was common enough among older customers that Odile decided the phone line would be advertised on every page of the website.
Requirements of different kinds
A functional requirement says what the software must do: let a customer cancel a booking. A non-functional requirement, also called a quality attribute, says how well it must do it or under what constraints: pages must load in under a second on a phone, or personal data must be deleted after a fixed time. Non-functional requirements are easy to forget because nobody asks for them in a meeting until they are missing, and they are often the hardest to add late. The team kept a separate list for them from the start.
| No. | Non-functional requirement | Why |
|---|---|---|
| N1 | Pages meet WCAG 2.2 level AA and work without JavaScript | Rosa and Jordan; the law and the shop's values |
| N2 | Pages work on a screen 320 pixels wide and on browsers up to five years old | Phones are the main device; Jordan's old phone |
| N3 | The 95th percentile time to serve a page is under 300 ms | The booking API's existing objective from the deployment course |
| N4 | Customer names and phone numbers are removed 30 days after the appointment | Collect and keep only what is needed |
| N5 | The website deploys through the existing pipeline with no manual steps | Leif's condition for running it |
| N6 | A booking reference cannot be guessed, and lookups are limited | Lessons from the API's security review |
User stories
For functional requirements, the team used user stories, the format most agile teams use. A user story is a short description of something a user wants, written from that user's point of view, usually in the template popularized by a team at the London company Connextra in 2001: As a role, I want a goal, so that a benefit. The template is not magic, but each part does a job. The role reminds the team who the story serves, the goal says what they want to do, not how the screen looks, and the benefit says why, which helps when the team later has to choose between two ways of doing it.
Ron Jeffries described a story as three things: the card, a few words that name it; the conversation, the discussion between the team and the client that fills in the details; and the confirmation, the tests that show it is done. The card is deliberately too short to be a specification. Its job is to be a promise to have the conversation, and that conversation is where the team learns, for example, that canceling must be possible up to two hours before the start because a mechanic plans the day's work at nine.
On Wednesday, May 17, the team, Ingrid and the three clients spent the evening writing stories on cards along the back room's long bench. To keep the cards consistent, Thierry wrote a small checker that reads each story and tells the author when it does not follow the template or names a role the team has not agreed on.
import java.util.*;
import java.util.regex.*;
public class Main {
record Story(String id, String role, String goal, String benefit) {}
static final Set<String> ROLES = Set.of("customer", "counter volunteer", "mechanic", "manager");
static final Pattern TEMPLATE = Pattern.compile("As an? (.+?), I want (.+?),? so that (.+)\\.?");
static Optional<Story> parse(String id, String text) {
Matcher m = TEMPLATE.matcher(text.trim());
if (!m.matches()) { System.out.println(id + ": does not follow the template"); return Optional.empty(); }
String role = m.group(1);
if (!ROLES.contains(role)) { System.out.println(id + ": unknown role '" + role + "'"); return Optional.empty(); }
String benefit = m.group(3).endsWith(".") ? m.group(3).substring(0, m.group(3).length() - 1) : m.group(3);
return Optional.of(new Story(id, role, m.group(2), benefit));
}
public static void main(String[] args) {
Map<String, String> cards = new LinkedHashMap<>();
cards.put("US-01", "As a customer, I want to see the next free repair times so that I can pick one that fits my day.");
cards.put("US-03", "As a customer, I want to cancel my booking without phoning, so that the time can go to someone else.");
cards.put("X-1", "The booking table needs a new column for the cancel time.");
cards.put("X-2", "As a user, I want a nice calendar so that it looks modern.");
cards.put("US-06", "As a counter volunteer, I want to see today's bookings so that I can check customers in.");
for (var e : cards.entrySet()) {
parse(e.getKey(), e.getValue()).ifPresent(s ->
System.out.println(s.id() + ": [" + s.role() + "] " + s.goal() + " -> " + s.benefit()));
}
}
}US-01: [customer] to see the next free repair times -> I can pick one that fits my day US-03: [customer] to cancel my booking without phoning -> the time can go to someone else X-1: does not follow the template X-2: unknown role 'user' US-06: [counter volunteer] to see today's bookings -> I can check customers in
What this code does
The regular expression has three groups for the role, the goal and the benefit, and the optional comma before so that accepts both punctuation habits seen on the cards. A card that is really a technical task, like X-1, fails the template, and one with the vague role user is refused so that the author must say which user. Optional lets main print only the cards that parsed, while the parse method reports why the others did not.
The two rejected cards taught something. X-1 was a real piece of work, but it was a task, not a story: no user wants a column. It belonged under a story, as one of the steps to deliver it. X-2 named no real user and no real benefit; when Ingrid asked who wanted a calendar and why, the honest answer was that Noemi liked the look of one, and the evidence from Saturday said customers wanted the next free times, not a month view.
Good stories: INVEST
Bill Wake proposed in 2003 a checklist for good stories that is still widely used, under the acronym INVEST. A story should be Independent, so it can be built in any order; Negotiable, a starting point for conversation rather than a contract; Valuable to a user or the client; Estimable, clear enough that the team can guess its size; Small, able to be finished within one sprint; and Testable, with a way to show it is done. The checklist is a set of questions to ask, not a scoring rule. The team turned a few of the questions into warnings that a program could raise, to catch the common slips before a person had to.
import java.util.*;
public class Main {
record Story(String id, String goal, int criteria) {}
static List<String> smells(Story s) {
List<String> out = new ArrayList<>();
String g = s.goal().toLowerCase();
for (String tech : List.of("database", "table", "column", "endpoint", "spring", "json"))
if (g.contains(tech)) out.add("names technology '" + tech + "' (Valuable?)");
if (g.contains(" and ")) out.add("goal joins two things with 'and' (Small?)");
if (s.criteria() == 0) out.add("no acceptance criteria (Testable?)");
for (String vague : List.of("easy", "fast", "nice", "user-friendly"))
if (g.contains(vague)) out.add("vague word '" + vague + "' (Testable?)");
return out;
}
public static void main(String[] args) {
List<Story> stories = List.of(
new Story("US-02", "book a free time for one bike with my name and phone number", 4),
new Story("US-03a", "find my booking and cancel it and rebook another time", 2),
new Story("US-05a", "an easy, fast booking page", 0),
new Story("US-08a", "a waitlist table in the database", 1),
new Story("US-07", "a text reminder the evening before my repair", 3));
for (Story s : stories) {
List<String> found = smells(s);
System.out.println(s.id() + (found.isEmpty() ? ": no warnings" : ":"));
found.forEach(f -> System.out.println(" - " + f));
}
}
}US-02: - goal joins two things with 'and' (Small?) US-03a: - goal joins two things with 'and' (Small?) US-05a: - no acceptance criteria (Testable?) - vague word 'easy' (Testable?) - vague word 'fast' (Testable?) US-08a: - names technology 'database' (Valuable?) - names technology 'table' (Valuable?) US-07: no warnings
What this code does
Each check looks for a pattern that often signals a broken INVEST property: technology words suggest a task rather than user value, an and in the goal suggests two stories in one, and vague adjectives or a missing criterion suggest a story nobody can test. The warnings name the property in question so the author knows what to ask, and they are only warnings, because a person must still judge. US-03a triggers the and check and was split into separate stories for finding, canceling and rebooking.
The warning on US-02 is a false alarm: its and joins two fields of one form, not two goals, which is exactly why the program warns rather than rejects. Splitting stories is a skill in itself. US-03a became three: find my booking, cancel my booking and, much later, change my booking to another time, which the team realized was just a cancel followed by a new booking and did not need its own feature at all. US-05a, an easy, fast booking page, was not a story but two non-functional requirements already on the list, N1 and N3, so it was torn up. The waiting list card, US-08a, was rewritten from the customer's side: as a customer, when the day I want is full, I want to be told if a time frees up, so that I do not have to keep checking.
Acceptance criteria
The confirmation part of a story is its acceptance criteria: the conditions that must hold for the client to accept it as done. The team wrote them in the Given, When, Then form that Dan North introduced with behavior-driven development in 2006. Given describes the starting situation, When the action, and Then the result that must be observable. The form is useful because each criterion becomes a test almost word for word, and because the client can read it and say whether it is right. Each criterion got an identifier made from its story's, such as US-03.2, so that a test could name the criterion it checks.
Story US-03 Cancel my booking
As a customer, I want to cancel my booking without phoning,
so that the time can go to someone else.
US-03.1 Given a booking for Saturday 10:30 and the time is Saturday 08:00
When the customer enters the reference and phone number and confirms
Then the booking is cancelled and the 10:30 start shows as free
US-03.2 Given a booking for Saturday 10:30 and the time is Saturday 09:00
When the customer tries to cancel it
Then the page says that bookings close two hours before the start
And it shows the shop's phone number
US-03.3 Given any booking
When the reference is correct but the phone number is not
Then the page says that no booking matches, exactly as for a wrong reference
US-03.4 Given a cancelled booking
When the customer looks it up again
Then the page shows that it was cancelled and whenWhat this code does
The four criteria cover the normal case, the two-hour rule Tamsin asked for, a security rule and what a customer sees afterwards. US-03.3 deliberately gives the same answer for a wrong phone as for a wrong reference, so a stranger cannot learn that a reference exists. Times are concrete, Saturday at 08:00, because a criterion with vague times cannot be tested.
Because the criteria would become tests, Thierry wanted them in a form a program could read. The next example parses criteria written in this layout into structured scenarios and reports any that lack one of the three parts, the most common slip being a Then that is missing because the author thought the result was obvious.
import java.util.*;
public class Main {
record Scenario(String id, List<String> given, List<String> when, List<String> then) {
boolean complete() { return !given.isEmpty() && !when.isEmpty() && !then.isEmpty(); }
}
static List<Scenario> parse(String text) {
List<Scenario> out = new ArrayList<>();
String id = null;
List<String> g = null, w = null, t = null, last = null;
for (String raw : text.split("\n")) {
String line = raw.trim();
if (line.isEmpty()) continue;
String[] parts = line.split("\\s+", 2);
if (parts[0].matches("US-\\d+\\.\\d+")) {
if (id != null) out.add(new Scenario(id, g, w, t));
id = parts[0]; g = new ArrayList<>(); w = new ArrayList<>(); t = new ArrayList<>();
line = parts[1]; parts = line.split("\\s+", 2);
}
switch (parts[0]) {
case "Given" -> last = g;
case "When" -> last = w;
case "Then" -> last = t;
case "And" -> { }
default -> throw new IllegalArgumentException("unexpected: " + line);
}
last.add(parts[1]);
}
if (id != null) out.add(new Scenario(id, g, w, t));
return out;
}
public static void main(String[] args) {
String text = """
US-04.1 Given a phone number with two active bookings
When the customer books a third start with that number
Then the page explains the limit of two active bookings
And no booking is made
US-04.2 Given a phone number with one BOOKED and one CANCELLED booking
When the customer books another start
US-04.3 Given a phone number with two bookings in the past
When the customer books a new start
Then the booking is made
""";
for (Scenario s : parse(text)) {
System.out.println(s.id() + (s.complete() ? " complete" : " INCOMPLETE")
+ ": " + s.given().size() + " given, " + s.when().size() + " when, " + s.then().size() + " then");
}
}
}US-04.1 complete: 1 given, 1 when, 2 then US-04.2 INCOMPLETE: 1 given, 1 when, 0 then US-04.3 complete: 1 given, 1 when, 1 then
What this code does
The parser starts a new scenario at each identifier and then files every line under Given, When or Then according to its first word, with And continuing whichever part came last. A line that starts with anything else is an error rather than being silently dropped. US-04.2 is reported incomplete because its author never wrote what should happen, and the team discovered that they did not agree on the answer.
The incomplete US-04.2 was a useful failure. Should a canceled booking count toward the limit of two? Hamza had assumed not, Thierry had assumed it did, and the code that Hamza had already written for version 1.5.0 counted only bookings with the status BOOKED. Odile settled it: only bookings that are still going to happen count, so the Then became the booking is made. A requirement that two developers read differently is a bug that has not happened yet, and writing the criterion is what found it.
Mapping the stories
A long, flat list of stories hides the shape of the product. Jeff Patton's story map, described in his 2014 book User Story Mapping, lays the stories out under the steps of the user's journey from left to right, the backbone, with the most necessary stories at the top of each column. A horizontal line across the map then marks a release: everything above the line is in the first version. The map makes it easy to see a first version that is thin but complete from end to end, rather than one that is perfect at booking and has no way to cancel.
Prioritizing with MoSCoW
Not everything on the map can be built in the term. The team used MoSCoW, a method devised by Dai Clegg at Oracle in 1994 and adopted by the DSDM agile framework, which sorts requirements into four groups. Must have means the release is useless or unacceptable without it. Should have means important, but the release still works without it. Could have means desirable if there is time. Won't have this time means agreed and recorded, but not in this release. The last group matters as much as the first: writing down what will not be done is what stops it from creeping back in.
DSDM adds a rule of thumb that the team adopted: the Must group should take no more than about three fifths of the available effort, so that when estimates turn out wrong, as they always do, there is room to drop Should and Could items and still deliver every Must. The team did not have estimates yet, so they gave each story a rough size in hours, small, medium or large, and checked the rule.
import java.util.*;
public class Main {
enum Priority { MUST, SHOULD, COULD, WONT }
record Item(String id, String name, Priority p, char size) {
int hours() { return switch (size) { case 'S' -> 8; case 'M' -> 20; case 'L' -> 40; default -> 0; }; }
}
public static void main(String[] args) {
List<Item> items = List.of(
new Item("US-01", "see free times", Priority.MUST, 'M'),
new Item("US-02", "book a repair", Priority.MUST, 'L'),
new Item("US-03", "find and cancel", Priority.MUST, 'M'),
new Item("US-04", "two active bookings per phone", Priority.MUST, 'S'),
new Item("US-05", "accessible pages (N1, N2)", Priority.MUST, 'M'),
new Item("US-06", "staff day list and check-in", Priority.MUST, 'M'),
new Item("US-07", "reminder text", Priority.SHOULD, 'M'),
new Item("US-08", "waiting list", Priority.SHOULD, 'L'),
new Item("US-09", "weekly figures", Priority.SHOULD, 'S'),
new Item("US-10", "repair-night stand sign-up", Priority.COULD, 'M'),
new Item("US-11", "pages in a second language", Priority.COULD, 'L'),
new Item("US-12", "online payment and accounts", Priority.WONT, '-'));
int budget = 225;
Map<Priority, Integer> hours = new EnumMap<>(Priority.class);
for (Item i : items) hours.merge(i.p(), i.hours(), Integer::sum);
int cumulative = 0;
for (var e : hours.entrySet()) {
cumulative += e.getValue();
System.out.printf("%-6s %3d hours (running total %3d of %d)%n", e.getKey(), e.getValue(), cumulative, budget);
}
int must = hours.get(Priority.MUST);
System.out.println("Must share of budget: " + must + "/" + budget + (must * 5 <= budget * 3 ? " within" : " OVER") + " three fifths");
System.out.println("everything up to Should fits: " + (hours.get(Priority.MUST) + hours.get(Priority.SHOULD) <= budget));
}
}MUST 128 hours (running total 128 of 225) SHOULD 68 hours (running total 196 of 225) COULD 60 hours (running total 256 of 225) WONT 0 hours (running total 256 of 225) Must share of budget: 128/225 within three fifths everything up to Should fits: true
What this code does
Each item's rough size becomes hours through a switch expression, and an EnumMap adds them up per priority in the enum's order, so the output always lists Must first. The check multiplies instead of dividing, testing must times five against the budget times three, to stay with whole numbers. The Must group fits within three fifths of the 225 focused hours, and Must plus Should fits too, but adding the Could items would not.
The output told the clients something they did not want to hear but needed to: the stand sign-up for Tamsin's repair nights and pages in Spanish were unlikely to make it. Tamsin took it well, since she had brought the idea mainly to have it written down. Odile asked for one change: the weekly figures, US-09, were cheap and would show the board whether the website worked, so they stayed in Should rather than drifting down. Online payment and customer accounts were put in Won't with a reason beside them: the shop takes payment when the bike is collected, and accounts would mean storing passwords for thousands of customers to save them typing a phone number.
| ID | Story (short form) | MoSCoW | Criteria |
|---|---|---|---|
| US-01 | As a customer, I want to see the next free repair times, so I can pick one that fits my day | Must | 3 |
| US-02 | As a customer, I want to book a time for one bike with my name, phone and problem, so I do not have to phone | Must | 6 |
| US-03 | As a customer, I want to find and cancel my booking without phoning, so the time can go to someone else | Must | 4 |
| US-04 | As the manager, I want each phone number limited to two active bookings, so a few people cannot hold every time | Must | 3 |
| US-05 | As a customer using a phone or assistive technology, I want pages that work for me (N1, N2) | Must | 5 |
| US-06 | As a counter volunteer, I want today's bookings with each problem, so I can check customers in and brief the mechanics | Must | 4 |
| US-07 | As a customer, I want a text the evening before, so I do not forget | Should | 3 |
| US-08 | As a customer, when my day is full, I want to hear if a time frees up, so I do not keep checking | Should | 5 |
| US-09 | As the manager, I want weekly figures for bookings, cancellations and missed appointments | Should | 2 |
| US-10 | As a repair-night visitor, I want to reserve a stand | Could | - |
| US-11 | As a customer, I want the pages in Spanish | Could | - |
| US-12 | Online payment and customer accounts | Won't | - |
Tracing requirements
A requirement is useful only if someone can later show that it was met. Traceability is the ability to follow each requirement forwards to the work and tests that deliver it, and each test backwards to the requirement it serves. In a large regulated project it can mean a separate tool and a document for each link; in a three-person capstone it meant a naming rule. Every acceptance criterion has an ID, every test method names the criteria it checks in its display name, and every pull request names its story. Thierry wrote the check that would run in the build once tests existed, and ran it on the first two stories with placeholder test names to see it work.
import java.util.*;
import java.util.regex.*;
public class Main {
public static void main(String[] args) {
Map<String, List<String>> criteria = new TreeMap<>(Map.of(
"US-01", List.of("US-01.1", "US-01.2", "US-01.3"),
"US-03", List.of("US-03.1", "US-03.2", "US-03.3", "US-03.4")));
List<String> testNames = List.of(
"US-01.1 shows the next free starts in order",
"US-01.2 skips Sundays, Mondays and holidays",
"US-03.1 cancels and frees the start",
"US-03.3 wrong phone looks like a wrong reference",
"US-03.3 wrong reference gives the same page",
"US-09.1 counts last week's bookings");
Pattern id = Pattern.compile("^(US-\\d+\\.\\d+) ");
Map<String, Integer> tested = new TreeMap<>();
Set<String> known = new HashSet<>();
criteria.values().forEach(known::addAll);
for (String t : testNames) {
Matcher m = id.matcher(t);
if (!m.find()) { System.out.println("test without a criterion: " + t); continue; }
if (!known.contains(m.group(1))) System.out.println("test names an unknown criterion: " + m.group(1));
else tested.merge(m.group(1), 1, Integer::sum);
}
for (var e : criteria.entrySet()) {
List<String> untested = e.getValue().stream().filter(c -> !tested.containsKey(c)).toList();
System.out.println(e.getKey() + ": " + (e.getValue().size() - untested.size()) + " of " + e.getValue().size()
+ " criteria tested" + (untested.isEmpty() ? "" : ", missing " + untested));
}
}
}test names an unknown criterion: US-09.1 US-01: 2 of 3 criteria tested, missing [US-01.3] US-03: 2 of 4 criteria tested, missing [US-03.2, US-03.4]
What this code does
The criteria map is the forward side of the trace, and the test names are the backward side, linked by the identifier at the start of each name. A test that names a criterion the map does not know, like US-09.1 here, is reported, because either the test or the list of criteria is out of date. The last loop shows each story's gaps, which later becomes a build step that fails when a Must story has an untested criterion.
The traceability check was a small investment that paid off at the security review and on demo day, when the team could answer the question every client eventually asks: how do you know it does what we agreed? But Ingrid warned against letting it become the goal. A criterion with a test is not necessarily a good criterion, and a team can satisfy the check with tests that prove nothing. The check finds gaps; it cannot judge quality.
Agreeing and changing
At the end of the evening Odile read the story list and the criteria for the six Must stories and said yes. That approval was recorded as a dated line in the repository, not because anyone expected a dispute, but because the list would change, and a change is only visible against a recorded starting point. The team agreed how changes would happen: anyone could propose a story at any time, but only Odile could move a story into or out of Must, and only at a sprint review, after the team had said what it would cost.
Tamsin had one last request as people were leaving: could the problem kinds on the booking form match the kinds on the shop's repair tickets, so that her morning list and the paper tickets used the same words? They could; the repair tickets already used five kinds, FLAT, BRAKES, GEARS, WHEEL_TRUE and TUNE_UP, and Hamza's ticket reports from the winter used the same ones. It became criterion US-02.4.
Exercises
Try it yourself
Split a story into its parts
Complete parts so that it returns the role, goal and benefit of a story written as As a ROLE, I want GOAL, so that BENEFIT. (the comma before so that and the final full stop may be missing), or null if the text does not follow the template. The program prints each card as shown in the expected output.
import java.util.*;
import java.util.regex.*;
public class Main {
static String[] parts(String text) {
return null;
}
public static void main(String[] args) {
List<String> cards = List.of(
"As a customer, I want to see the next free times, so that I can pick one.",
"As a mechanic, I want the day's problems so that I can plan the rack",
"Add a column for the cancel time.",
"As an manager, I want weekly figures, so that the board sees the effect.");
for (String c : cards) {
String[] p = parts(c);
System.out.println(p == null ? "not a story" : p[0] + " | " + p[1] + " | " + p[2]);
}
}
}Try it yourself
Does the Must group fit?
Each item is ID PRIORITY HOURS. Complete main so that it prints the total hours for each priority in the order MUST, SHOULD, COULD (skip WONT), then Must within three fifths: true or false for the budget of 180 hours, then the list of IDs that fit if the team takes items in the given order (all of MUST first, then SHOULD, then COULD) and stops before the first item that would go over the budget.
import java.util.*;
public class Main {
public static void main(String[] args) {
List<String> items = List.of("US-01 MUST 20", "US-02 MUST 40", "US-03 MUST 20", "US-04 MUST 8",
"US-07 SHOULD 20", "US-08 SHOULD 40", "US-09 SHOULD 8", "US-10 COULD 20", "US-12 WONT 0");
int budget = 180;
System.out.println("MUST 0");
}
}The team left the workshop with twelve stories, six of them Must, each Must with acceptance criteria the client had read, six non-functional requirements and a story map with a line across it. What they did not have was any idea how the pieces would fit together in code. That was the subject of the next Wednesday.
Common mistakes
MistakeAsking users in a meeting what features they want.
InsteadObserve users doing the real task and ask short questions about what they do now.
MistakeWriting tasks such as adding a column as stories.
InsteadWrite stories from a user's view and keep technical tasks under the story they serve.
MistakeUsing a vague role such as user.
InsteadName the agreed role, which tells the team whose need the story serves.
MistakeLeaving acceptance criteria for later.
InsteadWrite Given, When, Then criteria with the client before building, with concrete values.
MistakeForgetting non-functional requirements until the end.
InsteadKeep a separate, numbered list of quality attributes from the first week.
MistakeA Must list that takes all the available time.
InsteadKeep Must within about three fifths of the effort, and record the Won't items with reasons.
Summary and key terms
- The team observed real phone and counter bookings and a repair night before writing requirements, using contextual inquiry.
- Functional requirements became user stories in the template As a role, I want a goal, so that a benefit, and non-functional requirements such as accessibility, response time and data retention were kept in a separate numbered list.
- A story is a card, a conversation and a confirmation, and good stories follow INVEST: independent, negotiable, valuable, estimable, small and testable.
- Acceptance criteria in Given, When, Then form, each with an identifier, turn into tests and expose disagreements, such as whether canceled bookings count toward the limit.
- A story map arranges stories under the user's journey and marks a release line.
- MoSCoW sorts requirements into Must, Should, Could and Won't, with Must kept within about three fifths of the effort.
- Traceability links each criterion to the tests that check it, and only the client may move stories into or out of Must.
- Contextual inquiry
- Observing users doing a real task in the real place and asking short questions as they work.
- Functional requirement
- A statement of what the software must do.
- Non-functional requirement
- A statement of how well the software must work or under what constraints.
- User story
- A short description of something a user wants, written from that user's point of view.
- INVEST
- A checklist for stories: independent, negotiable, valuable, estimable, small, testable.
- Acceptance criteria
- The conditions that must hold for the client to accept a story as done.
- Given, When, Then
- A form for acceptance criteria: the starting situation, the action and the observable result.
- Story map
- Stories arranged under the steps of the user's journey, with lines marking releases.
- MoSCoW
- A prioritization into Must have, Should have, Could have and Won't have this time.
- Traceability
- The ability to follow each requirement to the tests that check it, and back.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Why did the team observe customers before writing stories?
Show answer
Because people predict poorly what they will want from new software but reliably show what they do now and what annoys them.
Why is a card such as add a cancelled_at column not a user story?
Show answer
It is a technical task with no user or benefit; it belongs under the story it helps deliver.
What did writing criterion US-04.2 reveal?
Show answer
That the developers disagreed about whether canceled bookings count toward the limit of two, which Odile then decided.
Why should Must items take no more than about three fifths of the effort?
Show answer
So that when estimates prove wrong, Should and Could items can be dropped and every Must still delivered.
What does the traceability check do, and what can it not do?
Show answer
It finds criteria without tests and tests without criteria; it cannot judge whether a test is any good.
Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.