Homework 3: Requirements

Translating designs into requirements

Now that you've completed Homework 2, you should have a detailed specification of your design, detailing every interactive detail (and likely many of the visual details) of your solution to the problem you selected. Your next task is to translate your design into a set of unambiguous requirements Links to an external site., each expressed in natural language.

Writing down requirements is useful for at least three reasons:

• The very act of articulating them will help you notice ambiguous or unstated assumptions about your design.
• Your list of requirements can act as an implementation to do list
• Your list of requirements will directly inform your testing plan
• Your list of requirements will be the basis of your homework 6 grade, which is assessed on the proportion of requirements that you've met. (Though this assignment isn't creating the final list you'll be held to; this is just a first draft. You'll have many chances to revise them before you begin your final sprint).

Each requirement should be a single, precise, verifiable fact that must be true about your implementation. Here's an example from our arithmetic practice example from homework 2 that violates all of these principles:

The system should count up all the answers and display them.

The statement above includes two requirements (counting and displaying), it's vague about what it means by "counting the answers" and "displaying" them, and because it's vague, it's not verifiable. Here's a better version of the counting requirement:

The system should compute the proportion of correct answers as the total number of correctly answered questions divided by the total number of questions asked.

That requirement is singular, precise, and verifiable.

Each of your projects has a different number of requirements, so I can't say how long your list needs to be. If I had to guess, I'd say you'll have anywhere from dozens to hundreds. Sound daunting? Here's your motivation: another way to think about requirements is as a complete to-do list for your implementation and testing work. The more complete, precise, non-conflicting, and verifiable your requirements, the easier it will be to get started, plan your effort, and ensure you can get the work done on time. All of those things are necessary for great engineering (and for a good grade in this class).

Create a requirements document in your GitHub repository, written in GitHub markdown. To make the requirements easier to navigate and understand, organize your requirements into sections, grouping sets of related requirements. Each section should be linked to a part of your design specification, when appropriate, so it's easier to understand what the requirements concerned. Each requirement should be precise, verifiable, and non-conflicting. The set of requirements overall should be complete with respect to your design specification.

To translate your design into requirements, review your design specification. Go through each part of it, identifying places where your specification states that something must be possible and convert all of those into requirements. You may also find that your design specification doesn't state that something is required, but you know it is required. Write these down as requirements as well.

In class

In Discord > Team Channels

DEVELOPERS lead

With your PM and Designer, read through your design specification draft and extract as many requirements as you can. To do this, follow the extracting requirements Links to an external site. strategy in HowToo, and leave a comment for 1 point. Remember that the comment must not be anonymous.

By the end of class, try to have a relatively complete list that's ready for evaluation and refinement before submission. You can use the rest of the week to finalize your submission.

Grading criteria

In addition to the 1 point for the non-anonymous strategy comment on HowToo, your team will need to submit a Markdown text file of your requirements document in your GitHub repository. (We'll use this as a snapshot of your requirements for future homeworks).

To incentivize you to be thorough in your requirements, your requirements will be graded on a 4 point scale, with the following possible deductions:

• Precision. Every requirement that could have been phrased unambiguously but was not loses 0.1 points. How precise? It should only one one interpretation.
• Verifiability. Every requirement that cannot be verified loses 0.1 points. How verifiable? If we can't think of a way to verify it, than it's not verifiable. (That means you should be able to think of a way to verify it).
• Conflicts. Every pair of conflicting requirements loses 0.1 points.
• Completeness. Every requirement the reader can think of that was not included loses 0.1 points. Think of every edge case!

Note that in this grading scale, it's really easy to get a zero if you don't think really carefully about every detail. Scour your design specification for every little detail, generating as many requirements as you can, and then generate even more. Remember that the more detailed you can get, the better your engineering to do list for later! Save yourself the future effort of generating these lists by doing a thorough job now, which will help you plan.

Also, if you're wondering how much detail to include in requirements (independent of precision and variability), focus on the details you really think matter for your design, and only include those. For example, if you're writing a requirement about an error message, and you're trying to decide whether to include the actual error message in the requirement, ask yourself: how much does the actual message matter for the qualities you're targeting? Maybe it really matters, and so you want to be sure to it's implemented exactly as specified. Maybe all that matters is that there is a message, but not what the message is. Use your discretion to decide what must be met, and focus on those details.

Fortunately, if I do find something missing, even though you'll lose points, you'll get an extensive list of feedback from me about ways to improve your requirements.