ICS 125:
Project in Software System Design
Fall Quarter 1999
Requirements
Due Date
As described on the course syllabus.
This document must be signed by your customer. This will
help ensure that he has agreed that you have met all his needs.
This is, after all, a contract with your customer.
Overview
After completing your prospectus, your team must develop a software
requirements document that satisfies the needs of your customer. This
document will consist of two primary components: a requirements
specification and a system test plan. Your design must also include a
glossary, or data dictionary, which defines all terms used that are
specific to the application you are developing. Other accompanying
documentation may be included as well.
In conjunction with this requirements specification, your team must
develop an acceptance statement and an initial system test plan covering the
requirements. 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.
As has been discussed in class, you have substantial flexibility in
choosing the specific form for the various sections of your deliverables. You've
done these before, in ICS 52 and ICS 121, so you have plenty of "model
documents" to draw from, to help you determine how to structure this statement.
A list of the standard items that must be turned in with each
ICS 125 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 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 to help
in the design phase (e.g., an OO requirements analysis can aid in development
of an OO design)
- Unambiguous: every reader will come away with the same understanding
- Consistent: no contradictions
- Abstract: one model, many realizations, and no implementation details
- Feasible: the requirements can be satisfied within resource constraints
- Even: the entire document is at same level of detail
- Effectively modifiable: this is a living document
- 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
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.
Understanding
Expand the understanding section of your original document
(prospectus). Make sure to add descriptions of what steps or actions
you took to understand each technology or software during this phase.
If you make changes to this section, add text describing why the change
was necessary, and why it more accurately reflects your new
understanding. This section need not be different if your understanding
hasn't changed.
Project Plan
This will be an iterative expansion of your previous submission. 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.
If you make changes, add text describing why the change was necessary
or why it will improve the ability of your team to accomplish the work
you have proposed.
Requirements Specification
You must, of course, provide a requirements specification.
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, software, and users of the system.
- Fixed Interfaces
Documents any interfaces to the environment that are fixed and hence
not part of the 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.
- Constraints
Non-functional constraints, including safety and security
constraints.
Quantifiable constraints (e.g., timing and precision).
- Goals
Documents any guidance for evaluating alternatives.
Lifecycle Considerations
Discusses capability subsets and/or product families for the purposes of
incremental development and potential changes.
Acceptance Requirements
Describes minimal requirements for system acceptance by the client, such
as the minimum capabilities that must be provided in the delivered system.
System Test Plan
Include a test plan capable of demonstrating minimal functionality
of all system elements:
test cases should be specified for each software capability specified.
NOTE: 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.
- For each test case
- 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
Defines all non-obvious terms used in the specifications above.
May include a detailed data dictionary.
Documentation
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.
See the syllabus for dates.
Each team should prepare a 15 minute presentation, after which we will
allow up to 5 minutes of questions. Your customer should be present.
Prepare your presentation appropriately. Your presentation should include
the following:
- Overview of your system;
- Current state of your project plan;
- Environment and interfaces;
- Highlights of your requirements specification including
- Summary of required capabilities, with a diagram if available;
one or more detailed requirements for the most important capabilities
(pick the key issues to discuss in detail);
- Lifecycle considerations
(how you intend to develop the system throughout the lifecycle);
- System test plan
how you intend to both demonstrate that the system should be accepted
as well as how you intend to convince yourselves that it is more than acceptable!).
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 he would like to see presented.