Part I: Functional Requirements
Part I of your Requirements Document should contain the following information.
System Purpose
Explain the purpose of your system. The basis for this explanation should be the system summary you wrote for Milestone 0. Incorporate any revisions that the course staff suggests when we hand back comments on your Milestone 0 submission. Your system purpose should answer the following questions:
- What is the problem to be addressed?
- Why is this problem worth solving? (What makes it hard, interesting, or challenging?)
- What will be the most important features of this system?
- Who might be the users of this system?
- What other systems already exist that those users might use instead?
- What new value will your system offer to those users?
Functional Requirements
Invent a list of functional requirements for the system you are building. For the purposes of this project, a functional requirement comprises the following data:
- User type. The type of user involved in this requirement.
- Assets. The critical information (or, in rare cases, physical objects) involved in this requirement.
- Importance. The importance of this requirement to your system's purpose.
Use the following "MoSCoW" scale to rank importance:
- M. Must have.
- S. Should have, if at all possible.
- C. Could have, but not necessary.
- W. Won't have now, but Would like to add later.
- A user story. A brief description of a single kind of interaction
a user can have with your system. User stories describe what
your system will do, but not how.
Here is a general template for a user
story: "As a user, I can action,
so that purpose." (See below for examples.)
The purpose clause of a story might be
obvious enough to omit the clause.
Good user stories satisfy the following "INVEST" criteria:
- Independent. Stories shouldn't overlap, and ideally you should be able to implement them in any order—though some orders might make more sense than others.
- Negotiable. Stories can change as your project evolves. However, you should view requirements you submit here as a contract proposal between your group and the instructor. You are responsible for fulfilling that contract and seeking approval of any major changes.
- Valuable. Stories add value to your system for users. The general template above ensures that you think in terms of that value. Stories shouldn't be about developers or attackers.
- Estimable. Stories' importance can be estimated, hence ranked. And stories' implementation time can be estimated. If you can't estimate, you probably don't understand the story. Consider adding more detail or breaking it into smaller stories.
- Small. Stories should be succinct, probably no more than one to four sentences.
- Testable. Stories represent testable goals. If you can't decide whether you've met a goal—that is, if you can't write a test that a skilled outsider could follow to determine whether your system fulfills a story—then your story isn't clear enough.
Here is an (incomplete!) example of five functional requirements, based on CMS:
| U. type | Assets | Import. | User story |
|---|---|---|---|
| professor | assignment | M | As a professor, I can create a new assignment by specifying its name, number of possible points, and due date. |
| student | submission | S | As a student, I can submit a file as a solution to an assignment. |
| grader | grade | M | As a grader, I can assign a number of points as a grade to a student for an assignment. |
| student | grade | S | As a student, I can view my grades for all assignments. |
| professor | survey | C | As a professor, I can conduct online surveys of students, so that I don't have to print and collect paper surveys. |
The last user story is not exemplary: it lacks estimability and testability, because it doesn't specify what a survey is, how students will take it, how results will be tabulated and presented, etc. It should be broken down into smaller stories. And this is likely how you will proceed with inventing requirements: write stories that are too "big" at first, then refine them.
You might find it helpful to organize your requirements in a spreadsheet, so that you can sort them in various ways.
How many requirements should we invent? It's impossible to give a general answer to this question: groups write at different levels of detail, have differently scoped projects (especially those using the 5431 project as their MEng project), and build systems with different tradeoffs between feature set size and implementation difficulty. What's important is not the number of requirements, but whether (i) they clearly fulfill your system purpose and (ii) satisfy the INVEST criteria.
Evaluation
We will evaluate Part I of your Requirements Document against the following criteria:
- Whether your document is easy to understand, well organized, and clearly written. Correct English style and usage counts here, just as it does in the real world.
- Whether the purpose of the system makes a persuasive argument for the effort you will spend in building the system.
- Whether the functional requirements seem sensible given the purpose of the system.
- Whether the functional requirements meet the INVEST criteria.