CS 240 - Requirements Specification

Due Mon Sep 30 at the start of class
Revisions due Wed Oct 02 at 11:59pm

Overview

As the first step for your project, each group will produce a Software Requirements Specification for its module. This document will detail the use cases you will support---in effect, it will describe the functionality of the software you will be delivering at the end of the semester. Upon finalizing this specification, your task will be to implement software that meets it.

Objectives

Details

Your document should be typeset using LaTeX---you are to turn in both the .tex source code as well as a final pdf.

Although there is no universal structure for requirements documents, your document should reflect the structure describing in the text and readings. (You might also be interested in IEEE Standard 830, a formal standard for such specifications). In particular, your specification should have the following sections:

  1. Cover Page

    Include a cover page with the title of the document, the name of your project and module, the names of all your team members, and other metadata (such as the date and a document revision number, if appropriate).

  2. Abstract/Executive Summary

    A short (aim for 150 words) summary of the document. It should give a very brief summary of the content of the document: "This document describes..." Imagine in ten years someone finds this document and wants to know what's in it, but doesn't want to read the whole thing. That's what the summary should detail.

    • HINT: Write this section last, once you know what is inside the document!
  3. Introduction

    A 1-2 page description of the module you will be implementing. This section should explain the context for the software. What is the overall product? What is the module described here? What is its purpose? Give me a brief overview of what the software will do, and why anyone should care. In short: what are you building and why?

  4. Functional Requirements/Use Cases

    This will be the bulk of your specification. Describe in detail each use case for your module: what functions are supported by the system, and how will the user perform those functions? Each use case should be formally described, including these attributes:

    • Name: A descriptive name for the use case.
    • Actor(s): A list of the actor(s) in the use case, with details if necessary.
    • Preconditions/Assumptions: Any special conditions that need to have been met before the use case can occur.
    • Flow of Events: The events that occur in this use case. These can be written in prose or as a list. You are welcome to use "subflows" if desired.
    • Alternatives: Details and events that may deviate from the main flow of events. Most commonly will be what happens when something "goes wrong" or otherwise doesn't work exactly as expected.
    • Postconditions: If appropriate, any details about the state of the system at the end of the use case.

    You should also include a UML use case diagram graphically detailing the relationship between your use cases. I like using Lucidchart for making UML diagrams, but Violet is also a good option for making simple diagrams.

    Note that depending on your module, your use case diagram may not be particularly complex. You may only have a couple of use cases (which perhaps have fairly complicated flows). Check in with me if you're unsure about how to structure your use cases!

  5. Nonfunctional Requirements

    List and briefly describe (in a sentence or two) the nonfunctional requirements for your product. Try to describe the nonfunctional requirements in a testable manner; how will you know if you've made the system "easy to use"?

  6. Glossary/References

    Finally, be sure to define the specialized terms you use (if any!), and to include citations to any references you make (e.g., if you reference any other systems as comparison points). Always provide proper attribution to other people's work.

Writing the Specification

For this assignment (as for the rest of the assignments in this course), there will be 5 people working on 1 paper. Thus you will need to put in the time and effort to coordinate and make sure that everyone contributes to producing a strong paper.

You should decide AS A GROUP on the high level details of your paper: what are the use cases? What pieces needed to be included? Once everyone is on the same page with deciding what the requirements are, you can begin writing the paper. You are welcome to divide the sections among the group (acknowledging that sections are different sizes) to complete individually, write sections as pairs, or just write the whole paper as a group---figure out what works well for your time!

How you split up responsibilities is your decision. Nevertheless, if there are any questions or concerns, let me know immediately so that I can help keep things on track.

One final note: the entire team should review and proofread the entire document. Five sets of eyes should look over the paper. And with that many people checking it, no typos or errors should get through!

Submitting

Your specification should be committed to the project repository (put it in the the "docs" folder)---be sure and upload both the .tex source code and the compiled pdf. Only one copy of the team's specification needs to be committed (it doesn't matter who actually pushes out the commit).

You will need to commit your document by Monday, Sep 30 at the start of class. I (as the "client") will look over the listed requirements that afternoon and let you know of any revisions that are needed. Requested revisions will focus on missing or poorly specified requirements, though you are welcome to make other changes as well. Revisions will need to be committeed by Wednesday, Oct 02 at midnight. While it is quite possibly to not have to do any revisions, you should set some time aside on Tuesday, just in case!

Each team member will also need to complete the first Peer Evaluation form by Wednesday at midnight.

Grading

Your requirements specification document will be graded on approximately the following criteria: