Requirements, User Stories and the Scope Document

Building the right thing

There is an old cartoon, passed around software offices for decades, about a tree swing. It shows what the customer described, what the analyst wrote down, what the programmer built and what the customer really needed: a different swing in every panel. It is funny because it is true. Many failed projects did not fail because of bad code. They failed because the team built the wrong thing very well.

The first planning deliverable, then, is a clear agreement about what the software must do. The curriculum asks you to create a software project plan by producing a software scope document and determining the tasks, deliverables and schedule. This lesson covers the scope document and the requirements inside it; the next two lessons cover tasks, deliverables and the schedule.

Gathering requirements (elicitation)

Requirements are not handed to you; you have to dig them out. Good analysts use several methods, because each one catches things the others miss:

• Interviews. Talk with the client and with real users. Start with open questions ("Walk me through what happens when someone borrows snowshoes."), then narrow down ("What if they want to borrow two pairs?"). Repeat back what you heard.
• Observation. Watch the current process. The LendIt team watched the front desk on a busy Saturday and saw that volunteers, not staff, handle most loans, which changed the usability requirements.
• Existing documents. Read the loan binder, the fee rules and the membership form. They reveal data you must store and rules you must follow.
• Surveys. Useful when there are many users; they give numbers ("8 of 10 volunteers have used a laptop at work").
• Prototypes. A paper sketch of a screen or a rough program often gets better feedback than any question, because people react to what they can see.

Also look for constraints from outside: laws and policies. For example, Canada's privacy laws expect organizations to collect only the personal information they need, and Ontario's accessibility law (the AODA) sets accessibility standards for many organizations' websites and services. These become non-functional requirements.

Functional and non-functional requirements

A functional requirement describes something the system does: an input, a calculation, an output, a rule. A non-functional requirement describes how well it must do it, or a limit it must respect: performance, usability, accessibility, reliability, security, privacy, the platform.

Each requirement gets an ID (R1, R2, ... for functional, N1, N2, ... for non-functional) so that later documents can refer to it: "test T14 checks R3". Here is LendIt's list after Priya and Jordan interviewed Denise.

What makes a requirement good?

A good requirement is:

• Testable: you can describe a test that passes or fails. "Fast" is not testable; "within 1 second with 500 items" is.
• Unambiguous: only one reasonable reading. "Members can borrow a few items" could mean 2 or 5; "at most 3 items at once" cannot.
• Necessary: someone actually needs it (it traces back to a stakeholder).
• Feasible: it can be built with the time, skills and budget available.
• About what, not how: "save all loans to files" leaves the design to the team; "use a CSV file with 6 columns" is a design decision, and belongs in the design document.

Watch for vague words: fast, easy, user-friendly, flexible, etc., and so on, quickly, nice. Each one hides a question you must ask the client.

User stories and acceptance criteria

Agile teams often write requirements as user stories, which keep the user and their reason in view:

As a role, I want goal so that reason.

A story is not finished until it has acceptance criteria: concrete examples that will become tests. A popular form is Given / When / Then: Given a starting situation, when something happens, then this is the result. Teams often write the story on the front of an index card and the criteria on the back.

Prioritizing with MoSCoW

There is never time for everything, so requirements are ranked with MoSCoW:

• Must have: the release is useless or illegal without it.
• Should have: important, but there is a workaround for a while (staff can scroll instead of search).
• Could have: nice extras if time allows.
• Won't have (this time): agreed to be out of this version. Writing these down is just as important as the Musts, because it prevents arguments later.

A common guideline is to keep the Musts to well under the time available, so that surprises eat into the Coulds, not into the deadline.

The scope document

The scope document (sometimes called a project charter or statement of work) pulls this together. It is short, usually one to three pages, and the client signs it. A typical scope document has these sections:

1. Background: the problem, in the client's words.
2. Objectives: what success looks like.
3. Stakeholders.
4. In scope: the requirements that will be delivered.
5. Out of scope: what will not be delivered.
6. Deliverables: every item that will be handed over.
7. Constraints: time, people, budget, technology.
8. Assumptions: things believed to be true that, if wrong, would change the plan.
9. Acceptance: how the client will decide that the project is finished.
10. Sign-off.

Checking requirements with a program

Requirements are data too. This script checks a few of LendIt's requirements for two common faults: vague words and missing acceptance tests (Won't items do not need one). It also counts the priorities.

The script turns each text into lower-case words, replacing full stops and commas with spaces so that "quickly." becomes "quickly". A word is flagged only if it matches a vague word exactly, so "fastest" would not be caught. A program cannot judge every requirement, but it can catch the easy mistakes before a human review.