Writing the Specification

From feature to use case

flowchart LR
  BO["BO-PERF-instructor-efficiency"] --> FEAT["FEAT-performance-tracking"]
  FEAT --> WAR["Area: WAR"]
  FEAT --> EVA["Area: EVA"]
  EVA --> UC["UC-EVA-submit-evaluation"]
  UC -.-> LATER["Design, code, test: week 8"]

Your first trace

Four volunteers

Shopper	The System	Fulfillment System	Billing System
a person	the online store	ships the order	charges the card

Use Case 01: Place an order

Main success scenario (1 of 2)

1. The Shopper indicates to order the items that have already been selected.
2. The System presents the billing and shipping information that the Shopper previously stored.
3. The Shopper verifies the information and confirms that the existing billing and shipping information should be used for this order.
4. The System presents the amount that the order will cost, including applicable taxes and shipping charges.
5. The Shopper verifies the information and confirms that the order information is accurate.
6. The System provides the user with a tracking ID for the order.
7. The System submits the order to the Fulfillment System for evaluation.
8. The Fulfillment System provides the System with an estimated delivery date.
9. The System presents the estimated delivery date to the Shopper.

Main success scenario (2 of 2)

10. The Shopper indicates that the order shall be placed.
11. The System requests the Billing System to charge the Shopper for the order.
12. The Billing System confirms that the charge has been placed for the order.
13. The System submits the order to the Fulfillment System for processing.
14. The Fulfillment System confirms that the order is being processed.
15. The System indicates to the Shopper that she has been charged for the order.
16. The System indicates to the Shopper that the order has been placed.
17. The Shopper exits the System.

Extensions

• 3a. The Shopper wants billing and shipping information different from what is stored. Also applies if nothing is stored, or the Shopper has no account.
  • 3a1. The Shopper indicates that this order shall use alternate billing or shipping information.
  • 3a2. The Shopper enters billing and shipping information for this order.
  • 3a3. The System validates the billing and shipping information.
  • 3a4. The use case continues.
• 5a. The Shopper discovers an error in the billing or shipping information in her account.
  • 5a1. The Shopper indicates that the billing and shipping information is incorrect.
  • 5a2. The Shopper edits the billing and shipping information in her account.
  • 5a3. The System validates the billing and shipping information.
  • 5a4. The use case returns to step 2 of the normal flow.

Run it again: the Shopper cancels

• 10a. The Shopper determines that the order is not acceptable (perhaps the estimated delivery date) and cancels the order.
  • 10a1. The Shopper requests that the order be cancelled.
  • 10a2. The System confirms that the order has been cancelled.
  • 10a3. The use case terminates.

What is a use case?

The system's behavior under various conditions, as it responds to a request from one of the stakeholders, called the primary actor.

Why use cases?

Ask users what they do, not what features they want.

Users can review a use case, because it is written in the words of their business.

You will meet user stories

"As a student, I want to submit my weekly activity report, so that my instructor can see my work."

• Card: the sentence
• Conversation: where the detail lives
• Confirmation: the acceptance tests

INVEST

• Independent
• Negotiable: not an explicit contract; the details are co-created during development
• Valuable
• Estimable
• Small
• Testable

Your agent does not negotiate

Find the right level

• Get a student loan
• Set up a promotion for Black Friday
• Handle a return for a customer
• Log in
• Move a piece on the game board

Three tests

What is in a use case?

Every step is a subgoal

Our template adds five things

• UC-<AREA>-<slug> identifier
• Trigger
• Business Rules, by BR-* identifier only
• Associated Information: data fields and validation
• Frequency of Use

Save your energy

• 1. Actors and goals: the use case list
• 2. Main success scenario, for the ones you pursue now
• 3. Failure conditions, all of them, before handling any
• 4. Failure handling

Three kinds of action step

• Interaction between two actors: "Clerk enters basic loss information."
• Validation protecting a stakeholder: "System confirms there are no competing claims."
• Internal change for a stakeholder: "System saves, and triggers acknowledgement be sent to agent."

Guideline 1: simple grammar

Subject ... verb ... direct object ... prepositional phrase.

Guideline 2: who has the ball?

At every step one actor has the ball, and that actor is the subject of the sentence.

Guideline 3: a bird's eye view

Guideline 4: move the process forward

• "User hits tab key." Why?
• To get to the address field. Why?
• She has to enter her name and address first.
• "User enters name and address."

Guideline 5: intent, not movements

Guideline 6: a reasonable set of actions

Guideline 7: "validates", not "checks whether"

Guideline 8: mention timing only when it matters

Usually the timing is obvious. Say it only when the requirement depends on it.

Guideline 9: "user has System A kick System B"

Guideline 10: "do steps x-y until condition"

3. User selects an item to buy, marks it for purchase.
4. System adds the item to the customer's shopping cart.

Customer repeats steps 3-4 until indicating that they are done.

5. Customer purchases the items in the shopping cart.

Standard mistakes: "Register for Courses"

1. Display a blank schedule.
2. Display a list of all classes in the following way: The left window lists all the courses in the system in alphabetical order. The lower window displays the times the highlighted course is available. The third window shows all the courses currently in the schedule.
3. Do
4. Student clicks on a course.
5. Update the lower window to show the times the course is available.
6. Student clicks on a course time and then on the "Add Course" button.
7. Check if the Student has the necessary prerequisites and that the course offering is open.
8. If the course is open and the Student has the necessary prerequisites, add the Student to the course. Display the updated schedule showing the new course. If no, put up a message, "You are missing the prerequisites. Choose another course."
9. Mark the course offering as "enrolled" in the schedule.
10. End do when the Student clicks on "Save Schedule."
11. Save the schedule and return to the main selection screen.

Corrected: "Register for Courses"

System: Course Enrollment System · Goal level: User Goal

1. Student requests to construct a schedule.
2. The system prepares a blank schedule form.
3. The system gets available courses from the Course Catalog System.
4. Student selects up to 4 primary and 2 alternate course offerings.
5. For each course, the system verifies that the Student has the necessary prerequisites, adds the Student to the course, marking Student as "enrolled" for that course in the schedule.
6. When the Student indicates the schedule is complete, the system saves it.

Extensions

• 1a. Student already has a schedule: System brings up the current version of the Student's schedule for editing instead of creating a new one.
• 1b. Current semester is closed and next semester is not yet open: System lets Student look at existing schedules, but not create new ones.
• 3a. Course Catalog System does not respond: The system notifies the Student and the use case ends.
• 5a. Course full or Student has not fulfilled all prerequisites: System disables selection of that course and notifies the Student.

A checklist for extensions

• Another way to succeed: "Clerk uses a shortcut code"
• The actor does it wrong: "Invalid password"
• The actor does nothing: "Password time-out"
• Every "validates": "Invalid account number"
• A supporting actor fails: "Response time-out"
• An expected internal failure: "Cash dispenser jams"
• An unexpected internal failure: "Corrupt transaction log"
• Too slow: "No response within 5 seconds"

Guideline 11: the condition says what was detected

Invalid PIN · Network is down · The customer walked away (time-out) · Cash did not eject properly

An extension is a miniature use case

• Trigger: the extension condition
• Goal: complete the use case goal, or recover from the failure just encountered
• Body: action steps, and possibly extensions of its own

Guideline 12: indent condition handling

Extensions

• 2a. Insufficient funds:
  • 2a1. System notifies customer, asks for a new amount.
  • 2a2. Customer enters new amount.

Our style guide

https://github.com/Washingtonwei/use-case-style-guide

Your turn: review a real use case

Project Pulse, UC-EVA-submit-evaluation (link in Slack)

• Alone, 5 minutes: list every defect.
• With your agent, 4 minutes: give it the use case and the style guide.
• Compare the two lists.

Two lists

They are requirements. They are not all of the requirements.

Before Friday

• No class Wednesday.
• Friday: the rest of the specification, in this room. There is no studio this week.
• Bring: your use case list (actors and goals only) and your feature-to-area table.
• Tomorrow, 10:00 AM: peer evaluation, in Project Pulse.

A pile of information

A senior manager gathered sixty employees for a day-long workshop on his company's next flagship product. Facilitators, brainstorming, ideas everywhere. He compiled it all into a hundred-page document and called it a requirements specification.

Nothing in it was classified, organized, or analyzed. The real requirements were in there somewhere. No developer could have found them.

The software requirements specification (SRS)

The functions the system must provide, its characteristics, and the constraints it must respect, described completely enough to say how the system behaves under various conditions, and how well.

• One per project, in docs/requirements/software-requirements-specification.md.
• Our template follows Wiegers and Beatty. The international standard is ISO/IEC/IEEE 29148.
• Kept current all term, like every other file in docs/.

It is not written for you

The specification is a hub, not a book

Constraints (2.4)

The one nobody asks

The assumption nobody wrote down (2.5)

Project Pulse's specification lists DE-gmail-smtp: email notifications depend on the Gmail SMTP integration.

It does not list the assumption underneath: that mail from a Gmail sender reaches a TCU inbox. TCU's filter can junk it. That is why you were told to add the address to your safe senders, in a course where a late peer evaluation is not accepted.

Every dependency and risk ends somewhere

Not everything is a use case (5.2)

FR-NOT-weekly-reminder

On a course section's weekly due day for activity reports or peer evaluations, the system shall email each student in that section a reminder listing what is due and when.

EARS: five shapes

"It says I haven't taken a training class in over a year."

Jackie, a chemist, needs more phosgene for her dyes. The chemical tracking system will not accept her request, so she calls Tim, the product owner.

Tim: Contoso requires an annual refresher class in the safe handling of hazardous chemicals. Corporate policy, based on OSHA regulations. The system just enforces it.

A property of the business (6)

Every rule has a source

• Who says so, and where it is written down.
• A syllabus section. A policy number. A regulation with a citation. A sentence your client said, with the date.
• No source? It is not a rule yet. It is an OPEN-ISSUES.md entry.

One more link in the chain

Data requirements (7)

A requirement document's status is DRAFT, SUBMITTED, RETURNED, or ACCEPTED.

Submitted goes to returned or accepted. Accepted is read-only.

Mars Climate Orbiter, September 1999

One team's ground software reported thruster impulse in pound-force seconds. The navigation software, built by another team, expected newton-seconds, as the interface specification required.

Every trajectory correction was off by a factor of 4.45. The spacecraft flew too low into the Martian atmosphere. A $327.6 million mission was gone.

External interfaces (8)

"I'm practically shouting over the fan and I'm getting hoarse."

Clarice is teaching in the new training room. She calls Sam, the maintenance supervisor: is the heating broken?

Sam: it is working normally. The right airflow, temperature held within half a degree from 60 to 85, every programming feature requested. Nobody said anything about noise, so I bought the cheapest unit that met the requirements.

An adjective is not a requirement (9)

Where did this number come from?

• Your client said it.
• You measured it.
• Your team decided it, and can defend it.

Your turn: where did this number come from?

• Your agent drafts section 9 of your specification, from your brief and your notes.
• Label every number client, measured, decided, or nobody knows.
• Every "nobody knows" becomes an OPEN-ISSUES.md entry, or gets deleted.

Before your next team meeting

• Agree your use case list, then split: four write one use case in full, one owns business-rules.md, one owns constraints and quality attributes.
• Both tables in docs/traceability.md, with their checks.
• Send the use case list to your client.
• Your TA checks all of it at the start of studio, Friday Sep 25.