Software Requirements: Specification & Analysis (SE463)

Spring 2021

To Go Directly to the Topics List

For Other Information including about Academic Integrity, Grievance, Discipline, Avoiding Academic Offenses, Appeals, and a Note for Students with Disabilities

Sections:

There are two nominally two sections. However, the notion of sections, whose purpose is to split the enrollment into groups each of which fits in one lecture room, is meaningless in an online course.

Instructor:

Evaluation of Instructor at the End of the Term

You will be able to evaluate the course instructor at http://evaluate.uwaterloo.ca any time between Thursday, July 22 at 11:59 pm and Thursday, August 5 at 11:59 pm.

TAs:

Class Communication:

If you have a question that is not private and is not targeted directly to one of the Instructors or TAs, then send it to se463 ATT uwaterloo DOTT ca, the course e-mail address.
One of the TAs or the instructor will answer it. If the question is deemed to be of general interest and not private, the answer, including the question WITH THE SENDER'S IDENTITY REMOVED, will be sent by e-mail to the whole class so everyone gets the benefit of the answer.

The main way that the class prof will announce things to the class is by e-mailing to everyone's watIam e-mail address. You are responsible for all information sent this way. If you prefer to receive such e-mail at a different address, please send e-mail to the course e-mail address from your watIam e-mail address, with the new e-mail address that you prefer given in the body of the message. To help you in case you delete any such messages too quickly, below you will find a link to an archive of every e-mail message sent in this manner.

Archive of E-mail Sent to Class:

Click Here for an archive of the e-mail sent to the entire class

Highest Level Course Outline:

  1. Overview
  2. Requirements Engineering Reference Model
  3. Requirements Modeling
  4. Requirements Elicitation
  5. Software Requirements Specification (SRS) document
  6. Requirements Writing
  7. Informal Specification Notations
  8. Specification of Non-behavioral Requirements
  9. Requirements Validation
  10. Cost Estimation
  11. Formal Specification Notations
The topics are listed in a rough order of dependency. However, the reality is that you are probably experienced enough that you can understand each topic somewhat independently. The topics that you probably will need to be able to do the project well are earlier in this list. See the Topics List for links to the material on each topic.

Recording Session Times:

This course is officially asynchronous. Therefore, there are videos of lectures at the course Web site, in the Topics List. There are regular live-lecture recording sessions that you are encouraged to attend. If you attend, you can have your questions answered immediately by asking them during the live lecture. Also, I need an audience to laugh at my jokes. Here are the days and times of the recording sessions:

The e-mail message that provides the Zoom link that you need to attend the recording sessions is the first in the archive of all e-mail sent to whole class. Note that the lecture is being recorded!

The student is responsible for knowing anything significant that arises from any in-class discussion that occurs in any lecture.

Readings:

No textbook. Notes are provided at this Web site.

References:

UML Cheat Sheets

IEEE Standard for SRSs

EVLA Array Operations Software Requirements, an example of a good SRS document

Example SRSs and Users' Manuals, including a local copy of the EVLA Array Operations Software Requirements (called "array-sw-rqmts.pdf")
There is also a template for SRSs in LaTeX form, called "srs.tex.txt". To use it as input to LaTeX, strip off the ".txt".

A link to the Website of Understanding Requirements, by David Gelperin, a book targeted to practitioners. The site has a collection of videos on various aspects of requirements engineering. Particularly interesting is Tutorial 1, "Simplistic Requirements Models Considered Harmful".

Workload:

Each group in this class is a team in the concurrent offering of SE 490. The TA that the group has in this class is the same that it has in SE 490. This TA serves as the group's mentor and evaluates the group's project-related work.
  1. group project: Some complete requirements specification of the identified scope of the system that is being prototyped in SE 490: This complete requirements specification can be in any of a number of forms, including, but not limited to: The key criterion for completeness is that the group, in writing the specification, is forced to flesh out all the requirements that are already present in the chosen scope of the system that is being prototyped in SE 490;
  2. some individual or group assignments, mostly directed at helping you in the group project; and
  3. a final assessment.
See the slides on Administration, Plans, and Requirements of the Course for more detail.

General Term-Independent Project Information

Evaluation:

The pre-pandemic distribution of the marks for the total grade was: You need to pass the final assessment in order to pass the course.

The assessment covers any and all material in the the Topics List. Part of the assessment is designed to be easier if you have actively participated in the project, so that overall, more of the final grade comes from the project work.

The above distribution was always tentative in two different ways:

  1. If the number of deliverables (assignments) change, the points for some of them will change so that for all of them, the total is 10%
  2. If the final assessment seems not to warrant 50%, then it may be made to count less and then the final deliverable will count less to bring the sum to 100%.

Current, Actual Evaluation:

The distribution of the marks for your total grade, adhering to current university regulations, which say that the final assessment can count no more than 20% of your total grade, is:

That is, each deliverable counts 1.6 times what it did, to make the deliverables count a total of 80%.

You need to pass the final assessment in order to pass the course.

The assessment covers any and all material in the Topics List.

If university regulations change on the worth of the final assessment, the above distribution will change.

Deliverables, How to Deliver Them, Group Numbers, and Due Dates

Deliverables

This is only the second time I am teaching this course when each group has a different system to write a specification for. In the past, every group wrote its own specification of single shared system, for which I served as the chief customer. I was able to be quite precise about what was expected in all deliverables and to even prepare my own solution to the early deliverables against which each group could check its own version. This precision is not possible now.

The descriptions of the deliverables here must be general enough to fit any system, but specific enough to make it clear what is expected of each deliverable. As the term progresses, expect that the descriptions of all deliverables will change, as I learn what is needed and what is possible.

The first three deliverables are the three artifacts described here:

All three of these should be based on the abstract you have already written for your project and have installed at the capstone repository.

If your team has not written an abstract yet, then the first deliverable includes the writing and installing of this abstract.

If, as a result of what it learns in the doing of any develiverable, your team changes its abstract, then say so in that deliverable and include in the deliverable both the before and after abstract, with the differences somehow highlighted.

On each due date, one of these artifacts, that was not delivered before, is due. They are actually listed in the most common order in which they are produced for any system. However, sometimes, for any given system, a different order is better. Your team should decide, in consultation with your TA, the best order in which to do them. Generally, you try to rank them in order of increasing amounts of information needed from other artifacts. The artifact that needs the least information from the others should be done first, and the artifact that needs the most information from the others should be done last. As each new artifact is done, you will discover that one or more previously delivered artifacts needs to be changed. When delivering any new artifact, the updated versions of all updated, previously delivered artifacts need to be delivered as well and included in the same file as the new artifact..

If your project is a research project and not an implementation project, then please talk with the prof ASAP so that you, your TA, and the prof can meet to negotiate a set of meaningful deliverables that help identify the requirements for your research. Yes. Even research often has requirements! :-)

If you find that a deliverable uses a notation that is not helpful or not relevant to your system, then please appraoch the prof ASAP so that you, your TA, and the prof can meet to find a notation, perhaps domain specific, that serves the deliverable's purpose, but is helpful and relevant to your system.

In particular, for any deliverable, if the domain in which your project is situated has its own established notation for expressing the content of the deliverable,

then please consult with the prof and your TA about using that notation instead of one described in the deliverable description.

If your team has started implementating already, then do not specify what you have implemented (aw! shucks!). Instead, specify the system that you and your customer had in mind when you wrote and refined your project's abstract that is at the repository. Remember, that at the time, you got your customer's buy-in to this intent. So he or she is expecting something similar to that intent. In particular, it is not acceptable to produce a specification that is built from your implementation upward. For an explanation, see these same words in the page on Thoughts on the Purposes of Writing a Requirements Specification.

How to Deliver Deliverables

     Group Numbers for Deliverables

Deliverable Due Dates

Due Date and Time Deliverable Details
   
Monday 31 May by 5:00pm Deliverable 1: One Artifact to the course e-mail address
   
Monday 14 June by 5:00pm Deliverable 2: One Artifact to the course e-mail address
   
Monday 28 June by 5:00pm Deliverable 3: One Artifact to the course e-mail address
   
Friday 16 July by 5pm Deliverable 4: First Draft Specification of Your System to the course e-mail address
   
Friday 23 July by 5:00pm Assignment 1: Ambiguity Exercise to the course e-mail address
   
Thursday 5 August by 5:00pm Deliverable 5: Final Draft Specification of Your System to the course e-mail address
   
Saturday 7 August at 12:30 -- 3:00PM EDT (2.5 hours synchronous)
If you are in a time zone whose awake hours do not include 12:30 -- 3:00PM EDT, you will have to do a time-zone shift. Plan ahead!
Final Assessment (Incomplete Policy            Sample Final Exams)
   

Example Solutions to Early Deliverables

You can find past whole-class projects and possible solutions to their early deliverables in the subdirectories of the directory PastProjectsAndDelivs.

Topics List

The URLs, particularly of published journal articles, conference articles, and books, should be exercised from within the University of Waterloo Library, where you can sign on with your watIam credentials. Then, you should not have to pay for a download.

The reason that the videos are recorded with the speaker's head bigger than usual and the slides smaller than usual, i.e., at 50% of the window each, is to allow the hearing impaired, such as the prof of this course, to read lips. See Instructions for Staging and Recording a Lipreading-Deaf-Accessible Video of a Lipreading-Deaf-Accessible Zoom Lecture in a Manner that Improves Accessibility to the Blind for an explanation. If you are having difficulty reading the smaller-than-usual slides, then please follow along with a local copy of the slides, downloadable from this site, or among the not-for-redistribution material sent to all registered students of this course.

The contents of this Topics List is evolving, both in the topics covered and in the content associated with each topic. Any video from a previous year is left in until it is replaced by a new one from this year's recording. Any video installed this year is marked with ``''.

                                                                         
Topic Prof's Slides and Videos Additional Reading Materials
     
Administration, Plans, and Requirements of the Course Main Slides: Administration, Plans, and Requirements of the Course  
  
  Video & Sound: Administration, Plans, and Requirements of the Course Chat Transcript of Video: Administration, Plans, and Requirements of the Course
     
RE Reference Model Main Slides: Requirements Engineering Reference Model Supplemental Slides: Traffic Light Example
  
  Video & Sound: Requirements Engineering Reference Model Part 1 Chat Transcript of Video: Requirements Engineering Reference Model Part 1
  
                         Explanation Specification as Program, Part 1, courtesy of Henry Pabst and Frank Wang Specification as Program, Part 2, courtesy of Henry Pabst and Frank Wang
  
  Video & Sound: Requirements Engineering Reference Model Part 2
from 00:00:00 to 00:45:35
Chat Transcript of Video: Requirements Engineering Reference Model Part 2
from 13:00:00 to 13:45:00
     
Classes, Concepts, and Domain Modeling Main Slides: Classes & Concepts Supplemental Slides: More on Domain Modeling for Deliverable
  
  Video & Sound: Classes and Concepts Part 1
from 00:45:35 to 01:25:56
Chat Transcript of Video: Classes and Concepts Part 1
from 13:45:00 to 14:25:00
  
  Video & Sound: Classes and Concepts Part 2 Chat Transcript of Video: Classes and Concepts Part 2
     
Use Cases and Scenarios Main Slides: Scenarios and Use Cases Supplemental Slides: User Requirements
  
  Video & Sound: Scenarios & Use Cases, Part 1 Chat Transcript of Video: Scenarios & Use Cases, Part 1
  
  Video & Sound: Scenarios & Use Cases, Part 2
from 00:00:00 to 00:18:40
Chat Transcript of Video: Scenarios & Use Cases, Part 2
from 13:00:00 to 13:18:40
     
Two Kinds of Requirements
Identifying Assumptions and Exceptions
Main Slides: Requirements Determination is Unstoppable Supplemental Slides: Administration, Plans, and Requirements of the Course
See Slides 26--43.
  
  Supplemental Slides: The Dangerous ``All'' in Specifications
See Slides 1--30.
Supplemental Slides: History of Formal Methods
See Slides 39--41, 46--51, and 60--65.
  
  "Exactly How Are Requirements Written?", Neil Maiden IEEE Software 29:1, 2012 Video: "Workarounds in Business Processes: A Goal-based Analysis", Nesi Outmazgin, Pnina Soffer, and Irit Hadar, CAiSE, 2020
  
  "Names that Make Computers Go Crazy", Gojko Adzic Humans vs Computers, Gojko Adzic
You can download a free sample, which has some interesting stuff and it lists all the examples in the book, and you can see the book's table of contents.
  
  Moshe Vardi: "Lessons from COVID-19: Efficiency vs. Resilience"  
  
  Video & Sound: Finding Exceptions and the Effect of Not Finding Them, Part 1
from 00:18:40 to 01:21:30
Chat Transcript of Video: Finding Exceptions and the Effect of Not Finding Them, Part 1
from 13:18:40 to 14:21:30
  
  Video & Sound: Finding Exceptions and the Effect of Not Finding Them, Part 2
from 00:00:00 to 01:10:10
Chat Transcript of Video: Finding Exceptions and the Effect of Not Finding Them, Part 2
from 13:00:00 to 14:10:10
  
  Video & Sound: Tacit Assumptions
from 0:10:49 to 0:19:20
Chat Transcript of Video: Tacit Assumptions
from 13:10:49 to 13:19:20
     
User Interfaces Main Slides: User Interface Specifications  
  
  Exiting a textEdit Session Exiting an MS Word Session
  
  "Interface Quotas and Internet-Derived Value", Bob Colwell, IEEE Computer 37:12, pp. 10-12, 2004  
  
  Video & Sound: User Interface Specifications, Part 1
from 01:10:10 to 01:20:27
Chat Transcript of Video: User Interface Specifications, Part 1
from 14:10:10 to 14:20:27
  
  Video & Sound: User Interface Specifications, Part 2
from 00:00:00 to 00:56:25
Chat Transcript of Video: User Interface Specifications, Part 2
from 13:00:00 to 13:56:25
     
Users' Manuals Main Slides: Users' Manuals as Requirements Specifications Supplemental Slides: User's Manual Advice
  
  Video & Sound: Users' Manuals as Requirements Specifications, Part 1 Chat Transcript of Video: Users' Manuals as Requirements Specifications, Part 1
  
  Example User's Manual for WD-pic  
  
  Video & Sound: WD-pic Manual
from 00:00:00 to 00:23:17
Chat Transcript of Video: WD-pic Manual
from 13:00:00 to 13:23:17
     
Ambiguity in Requirements Specifications Main Slides: Ambiguity in Requirements Specifications Supplemental Slides: The Dangerous ``All'' in Specifications
  
  Video & Sound: Ambiguity in Requirements Specifications: Part 1
from 00:23:17 to 01:24:08
Chat Transcript of Video: Ambiguity in Requirements Specifications: Part 1
from 13:23:17 to 14:24:08
  
  Supplemental Slides: Some "only" Exercises for Class All the sentences with "only" in the EVLA Array Operations Software Requirements.
  
  Google search for "I eat only" Google search for "I only eat"
  
  Video & Sound: Ambiguity in Requirements Specifications: Part 2 Chat Transcript of Video: Ambiguity in Requirements Specifications: Part 2
  
  Google search for "All eat" Google search for "Each eats"
  
  Google search for "Both eat"  
  
  Video & Sound: Ambiguity in Requirements Specifications: Part 3
from 0:00:00 to 0:10:49
Chat Transcript of Video: Ambiguity in Requirements Specifications: Part 3
from 12:58:00 to 13:10:49
     
SRSs Main Slides: SRSs Supplemental Slides: Points in the SRS's Space of Requirements
Each requirement is a green dot.
  
  IEEE Standard for SRSs 21 Top Engineering Tips, for Writing an Exceptionally Clear Requirements
  
  "A Standard Plan for Modern Requirements", by Bertrand Meyer, a proposal for an update to the IEEE Standard Meyer's paper annotation to show relationship with the RE Reference Model
  
  Video & Sound: SRSs
from 00:56:25 to 01:24:00
Chat Transcript of Video: SRSs
from 13:56:25 to 14:24:00
  
  EVLA Array Operations Software Requirements Example SRSs and Users' Manuals, including a local copy of the EVLA Array Operations Software Requirements (called "array-sw-rqmts.pdf")
There is also a template for SRSs in LaTeX form, called "srs.tex.txt". To use it as input to LaTeX, strip off the ".txt".
     
Requirements Elicitation Main Slides: Elicitation Supplemental Slides: Elicitation
  
  Supplemental Slides: Stakeholders  
  
  Video & Sound: Elicitation
from 0:19:20 to 1:14:30
Chat Transcript of Video: Elicitation
from 13:19:20 to 14:14:30
     
Non-Functional Requirements Main Slides: Nonfunctional or Quality Requirements  
  
  Video & Sound: NFRs, Part1
from 1:14:30 to 1:24:59
Chat Transcript of Video: NFRs, Part1
from 14:14:30 to 14:24:59
  
  Video & Sound: NFRs, Part 2
from 0:00:00 to 0:33:40
Chat Transcript of Video: NFRs, Part 2
from 1:00:00 to 1:33:40
     
Cost Estimation Main Slides: Cost Estimation Cost Estimation
  
  Video & Sound: Cost Estimation, Part 1
from 0:34:48 to 1:21:59
Chat Transcript of Video: Cost Estimation, Part 1
from 1:34:48 to 2:21:59
  
  Video & Sound: Cost Estimation, Part 2
from 0:00:00 to 0:24:27
Chat Transcript of Video: Cost Estimation, Part 2
from 13:00:00 to 13:20:27
  
  Software Engineering Economics, by Barry Boehm, Prentice Hall, Englewood Cliffs, NJ, USA, 1981 (Pages 39-41 and 381-386) [Scan sent by e-mail to students registered in the class]  
  
  Requirements Determination is Unstoppable The Requirements Iceberg
     
RE for AI and ML RE for AI and ML, Problems and Solutions RE Reference Model for AI and ML
  
  Instability in AI and ML Recall vs. Precision vs. Recall in NLP tools for RE, and for AI and ML
  
  Requirements for Monitoring Inattention of the Responsible Human in an Autonomous Vehicle: The Recall and Precision Tradeoff RE for AI Summary
  
  Recall vs. Precision vs. Summarization in RE for AI  
  
  Video & Sound: RE for AI and ML, Part 1
from 0:24:27 to 1:22:01
Chat Transcript of Video: RE for AI and ML, Part 1
from 13:20:27 to 14:20:00
  
  Video & Sound: RE for AI and ML, Part 2 Chat Transcript of Video: RE for AI and ML, Part 2
  
  Video & Sound: RE for AI and ML, Part 3
from 0:00:00 to 0:57:00
Chat Transcript of Video: RE for AI and ML, Part 3
from 13:00:00 to 13:57:00
  
  Video & Sound: RE for AI and ML, Part 4
from 0:32:25 to 1:24:41
Chat Transcript of Video: RE for AI and ML, Part 4
from 13:32:25 to 14:24:41
     
Verification and Validation Inspections and Validation  
  
  Video & Sound: Inspections
from 0:00:00 to 1:07:00
Chat Transcript of Video: Inspections
from 13:00:00 to 14:07:00
     
State Machines Main Slides: State Machine Diagrams Linear Temporal Logic Exercises
  
  Video & Sound: UML State Machines, Part 1
from 1:07:00 to 1:20:35
Chat Transcript of Video: UML State Machines, Part 1
from 14:07:00 to 14:20:35
  
  Video & Sound: UML State Machines, Part 2 Chat Transcript of Video: UML State Machines, Part 2
  
  Supplemental Slides: State Machine Diagrams Prof. Sakhnini's Solution 1 and Prof. Sakhnini's Solution 2
     
Linear Temporal Logic Main Slides: Linear Temporal Logic Supplemental Slides: System state of a State Machine
  
  Video & Sound: Linear Temporal Logic, Part 1
from 30:10 to 1:22:48
Chat Transcript of Video: Linear Temporal Logic, Part 1
  
  Video & Sound: Linear Temporal Logic, Part 2 Chat Transcript of Video: Linear Temporal Logic, Part 2
  
  Video & Sound: Linear Temporal Logic, Part 3 Chat Transcript of Video: Linear Temporal Logic, Part 3
  
  Linear Temporal Logic Exercises  
     
General Overview of RE Main Slides: The Requirements Iceberg The Requirements Iceberg Bibliography
  
  Video & Sound: The Requirements Iceberg, Part 1 Chat Transcript of Video: The Requirements Iceberg, Part 1
  
  Video & Sound: The Requirements Iceberg, Part 2 Chat Transcript of Video: The Requirements Iceberg, Part 2
  
  Video & Sound: The Requirements Iceberg, Part 3 Chat Transcript of Video: The Requirements Iceberg, Part 3
  
  Video & Sound: The Requirements Iceberg, Part 4 Chat Transcript of Video: The Requirements Iceberg, Part 4
  
  Video & Sound: The Requirements Iceberg, Part 5 Chat Transcript of Video: The Requirements Iceberg, Part 5
  
  Contains: K. Forsberg and H. Mooz, System Engineering Overview, by Kevin Forsberg and Harold Mooz, in Software Requirements Engineering, Second Edition, ed. Richard H. Thayer and Merlin Dorfman, IEEE Computer Society Press, Washington (1997), pp. 44-71 (This takes a while to download, because it's a bit map.) "Why did your project fail?", Narciso Cerpa and June M Verner Communications of the ACM 52:12, 2009
  
  Chapters 3 and 4 of Lihua Ou's Thesis Analysis of Ou Data: Estimated Agile and Waterfall Lifecyles
  
  Distribution of Requirements Defects Some Questions to Ask Yourselves About Your Deliverables 4
  
  Recall vs. Precision vs. Summarization in RE for AI  
  
  Supplemental Slides: Survey Results About How Agile Development is REALLY Done "1.4 Threats to Software Security" from Software Security Engineering: A Guide for Project Managers, by Julia H. Allen, Sean Barnum, Robert J. Ellison, Gary R. McGraw, Nancy R. Mead, Published May 1, 2008 by Addison-Wesley Professional. Part of the SEI Series in Software Engineering series. [Scan sent by e-mail to students registered in the class]
     
Real Life, Small Scale Requirements Engineering:
A Covid-19 Era Self-Administered Haircut
Main Slides: My Self-Administered Hair Cut During the Covid-19 Lockdown Supplemental Video: After the Self-Administered Hair Cut
  
  Video & Sound: My Self-Administered Hair Cut During the Covid-19 Lockdown
from 0:59:06 to 1:19:59
Chat Transcript of Video: My Self-Administered Hair Cut During the Covid-19 Lockdown
from 13:59:06 to 14:19:59
  
  Video & Sound: A fully captioned redelivery of the Haircut Video recorded nearly a year later  
     
Case Studies
(Some Duplicates with Other Topics)
Main Slides: Requirements Engineering for a Synagogue's Kitchen  
  
  Place Holder for Possible Eventual Video  
  
  Requirements Determination is Unstoppable Report on the Davis Centre Atrium Doors
  
  Oh God I'm Not Getting a Return Offer: Why You Should Really Practice Requirements Engineering Requirements Engineering for Parking Lot A at UW
     
Internet History and Requirements Celebrating the 50th Anniversary of the Birth of the Internet. Setting the Course for the Next 50 Years The site has captioned videos of the talks given at the celebration on 29 October 2019, at UCLA! Editorial by Len Kleinrock that discusses the requirements for the ARPAnet, which later became the Internet.
  
  "Requirements for the Internet", V.G. Cerf, 11th IEEE International Requirements Engineering Conference, pp. 3-4, 2003 "Vint Cerf: The internet and 40 years of openness", Cliff Saran, ComputerWeekly.com, 22 Aug 2013
  
  "Origins of the Internet", Leonard Kleinrock, Distinguished Lecture Series, Cheriton School of Computer Science, University of Waterloo, 17 May 2021  
     

This page is at http://www.student.cs.uwaterloo.ca/~se463/index.shtml


SE463: Software Requirements and Specification
Last modification: Friday, 30-Jul-2021 14:59:47 EDT