Informatics 117: Project in Software System Design

Winter Quarter 2009

Requirements

Due Date: January 27th (Thursday)

This document must be signed by your customer. This will help ensure that he or she has agreed that you have met all his or her needs. This is, after all, a contract with your customer.

Assignment Overview

Develop a software requirements document that satisfies the needs of your customer. This document consists of three primary components: (1) a requirements specification, (2) a system test plan, and (3) an update to your project plan. Your design may also need to include a glossary defining key terms used that are specific to your application. Other accompanying documentation may be included as well.

The system test plan must cover all basic software capabilities to be provided by the system by applying functional test heuristics (black box) to each capability described in the requirements specification and developing a test case for each interaction between capabilities.

You have substantial flexibility in choosing the specific form for the various sections of your deliverables. "Model documents", drawn from previous classes such as ICS 52 or from numerous Web sources, may be drawn upon, to help you determine how to structure this statement.

A list of the standard items that must be turned in with each assignment and posted on the team's web site are in the course syllabus. Required sections of this document are described below.

Deliverable Objectives/Requirements Qualities

Keep in mind that key objectives of a requirements document are to:

Document the customer's needs
Identify functional capabilities to be provided
Identify non-functional and environmental constraints that must be satisfied
Provide a definitive basis for testing and verification
Identify lifecycle considerations such as incremental sub-system development
Provide a reference tool readable by and useful to customer, developer, and maintainer
Serve as a contract between customer and developer

In addition, keep in mind that a requirements document should possess the following qualities:

Complete: everything that is essential is described
Understandable: the "customer" can read it and be convinced that all his objectives and needs are adequately and accurately described
Utility: the information in the document can be used effectively as the design progresses
Unambiguous: every reader will come away with the same understanding
Consistent: no contradictions
Feasible: the requirements can be satisfied within resource constraints
Concise and appropriate: no extraneous details and not more than required
Verifiable and testable: you can tell when you've met the requirements

Required Document Contents

Introduction (Required)

Provide an introduction that discusses the scope and purpose of this document as well as your specific approaches related to the requirements of the system. This introduction should also discuss the organization of this document and guide the reader. (In other words, this section not about the substance of your project, but rather the choices you made in describing the requirements.) Probably a very short section.

Project Summary (Required, but short!)

This section need not be different from that included in your prospectus if your understanding hasn't changed.

Requirements Specification (Required)

Use diagrams to help give appropriate overviews and understanding. Note that pictures may well be an essential element of the complete description of any graphical interface. Some suggested contents follow.

Overview of System Requirements: Provides a brief discussion of basic needs and proposed usage.
Environment Characteristics: Describes hardware environment, overview of the software package to be developed (e.g. will it be a desktop app distributed via DVD? a web site? a downloadable app for an iPhone? etc.), and users of the system.
Fixed Interfaces: Documents any interfaces to the environment -- hardware or software -- that are fixed and hence not part of your design of the system (e.g. an external database).
Software Capabilities: Specifies functionality in groups of related capabilities. A diagram is helpful to show the relationship between capability groups.
For each capability, at least the following should be specified: Description (functionality of the capability group), Input, Output, Persistent Data (that lasts from one invocation of the system to the next). Considerations specific to the application domain and other relevant fields may be provided too.
Sample I/O or Scenario: Provides a sample input/output stream describing user interaction with the system, or similar usage scenario. NOTE: if useful, the streams can be grouped with the capability group to which they apply.
Non-functional properties: including safety and security constraints, timing and precision, ....
Goals: Documents any guidance for evaluating alternatives as the design progresses.

Lifecycle Considerations (Required)

Prioritized capability subsets for the purposes of guiding incremental development. (Don't repeat content; use references to items in the preceding section).

Acceptance Requirements (Required)

Describes minimal requirements for system acceptance by the client, such as the minimum capabilities that must be provided in the delivered system. This should logically tie in closely with the preceding section (Lifecycle considerations). (Don't repeat content.)

System Test Plan (Required)

A test plan capable of demonstrating minimal functionality of all system elements: test cases or strategies should be specified for each software capability specified. If desired, the test cases can be grouped with the capability group to which they apply, otherwise a cross reference listing of some sort should be provided.

Each test case could be described as follows:

Test Case ID
Purpose of test case
Item(s) being tested
Input specification
Output specification (Expected Results or Test Oracle Mechanism)
Test environmental needs or special test procedures

Glossary (Optional)

Defines all non-obvious terms used in the specifications. May include a detailed data dictionary.

Project Plan (Required)

Expand your project plan to represent how you have accomplished the work so far. Reassess the project risks. Expand your task network or work breakdown structure to include the effort expended to complete this task. Based on the work you have done, revise your estimates on how much your team can accomplish and deliver. Provide a rationale for any significant changes to the original plan.

Auxillary Documentation (Optional)

This section is reserved for any documentation you may have developed during this phase of the project. Specifically, if during the course of developing the your understanding of the various technologies involved in the project, you discovered items that were not documented, but which were important, then you should include that here. Additionally you should list here the major background sources of information that you used during this phase or any that you plan to use during the remainder of the project. This would include references to similar systems and/or procedures.

Requirements Presentations/Reviews.

January 27 or 29 (at your discretion).

Each team should prepare a 15 minute Powerpoint presentation, after which we will allow for questions. Your customer should be present.

Prepare your presentation appropriately. Your presentation should include the following:

Overview of your system;
Highlights of your requirements specification
System test plan
Current state of your project plan; highlight items that have changed since the initial project plan;

Be sure to focus your presentation on the key issues. Don't spend time with the obvious things. If there's something in your presentation that you find boring, so will your audience. Don't gloss over problems. Your customer wants you to succeed, your instructors want you to succeed. They can't help you unless you tell them where you think the problems are, or are likely to be.

You should also ask your customer what they would like to see presented.