CSE 432S/533S: Project Requirements

This page is intended to help each project team define the requirements for the first design and development cycle. The requirements defined in this stage will also carry forward into the second design and development cycle with refinements and possibly additional requirements for the second cycle.

Guidelines for Defining Requirements

Project requirements should provide a comprehensive definition of what the project will achieve, though at a reasonably high level. Requirements should be stated as complete sentences containing words like "should" and "will" for strict requirements that must be met for the project to be considered successful. In addition to those strict requirements, which define the project's basic scope, additional optional requirements may be defined. Optional requirements should state any nessary preconditions using words like "if", "in case", "under the condition that", etc., and should use words like "may" or "could" to indicate that while the project would be enhanced by meeting the requirement, it still can be judged a success without doing so.

Ideally, the strict requirements for the project should be complete enough that even if none of the optional requirements are met, a complete and high quality high level design, low level design, implementation, and evaluation can be achieved without significant revision or expansion of the set of strict requirements for the project. This is very important, as the set of strict requirements defines the scope of the project, and in that sense establishes expectations for the amount and kind of effort required to complete the project.

All requirements for the project should be detailed enough that they can be followed into the selection of appropriate design patterns. That is, they should adequately capture the design forces against which design pattern problem and context descriptions can be compared. In your requirements document, you should try to list the relevant design forces pertaining to each stated requirement, as explicitly as possible.

In practice it is sometimes difficult to anticipate all of the considerations that will come up during design and implementation up front, and it is sometimes necessary and beneficial to revisit requirements during later stages. Beware, however, of letting the scope of the project change (sometimes known as "scope creep") as that can put the timeline and quality of the project in jeopardy.

The cost (in this course mainly in terms of time, but in real-world projects also often in terms of money and in some cases in terms of health and safety risks) of revisiting requirements increases non-trivially as a function of the number and scope of subsequent design and implementation decisions that themselves must then be revisited. Therefore, even at the stage, it is thus important to look ahead at least to the high level design stage (and if possible even further sometimes), and to try to anticipate whether the set of requirements stated will be sufficient and appropriate looking ahead. One suggestion is to skim the brief pattern summaries on the inside cover of the GoF book and see if any of them seem to have bearing on the requirements you are generating. You can then review those patterns that appear possibly relevant in more detail as you write your requirements, and focus on whether those patterns may suggest other requirements that have not been captured.

This suggested approach can also result in development of a partial skeleton for your high level design while you complete your requirements definition, and can help you both to evaluate your requirements and to get a head start on transitioning from requirements into high level design. Whether a given set of requirements is complete is ultimately a matter for you to judge, and building your experience in making such judgements is an important part of the design experience in this course. You will have two passes through the project and its requirements, so a thorough first attempt should serve you well even if you do need to revise your requirements to some extent in later stages.

Examples of Requirements

The "Fundamentals" section of Chapter 2 in the Pattern Hatching textbook begins (on page 14) with a nice example of the kind of requirement statements you should aim to write for your projects. First, it identifies from whose perspective the requirements are given since there may be distinct (and sometimes competing) perspectives from which a complete set of requirements should be written. Such perspectives are often associated with "actors", which represent people or other sources of decisions and actions that are relevant to the project, and which are often preserved in the design, implementation, and even evaluation stages (for example, "does this web page load quickly enough to avoid annoying our customers?").

To quote from that section, these examples are worth emulating:

"From the user's perspective, a file system should handle file structures of arbitrary size and complexity. It shouldn't put arbitrary limits on how wide or deep the file structure can get."
"From the programmer's perspective, the representation of the file structure should be easy to deal with and extend."

The section then continues by identifying the main objects with which the requirements are concerned (files and directories), and then goes on to describe the relationships between them, and thus reveals additional requirements like "You also want to accommodate new kinds of files (symbolic links, for example) without reimplementing half the system." This further evolution is very important in making sure you end up with a complete set of requirements (or at least an easily extended set if you miss one or two initially).

Other Sources of Information

The projects mentioned in the Project Definition web page are also useful sources of information in developing requirements, and we'll point out several ways those sources serve to illustrate both what goes into writing a good requirement and how to write up requirements.

Mike Sorensen's medical information system design document is more an example of a high level design document (moving toward low level design) than of a requirements document. However, it captures a number of details that should be expressed in the requirements document. For example, Section 3 (Design and Implementation) of that document defines who the actors are (patients and providers), the objects on which they act (different kinds of files and folders containing medical information such as case histories), and the kinds of actions (referrals, for example) that can be performed on those objects.

Tom Judkins' design document for his project also gives a mixture of design and requirement information. It gives background information about the problem domain, and also states high-level project requirements ("Requirements" with a capital "R") like "Each sound module in the analog synthesizer will be represented by a corresponding software object." In this document, high-level project requirements are also interspersed with low-level design requirements ("requirements" with a lower case "r") like "Each module will extend from an abstract base class, and will support polymorphism."

Deliverable: Requirements Document

Using Word, LaTeX, or other editing tools as you prefer, you will produce a document that describes your plan for the current development cycle in your project and that contains the following sections:

a cover page with the title of the project, the nature of the document (requirements), the names of the team members who contributed materially to the document, and the date the document was submitted;
an overview of the planned project and any introductory information needed to understand what it is about;
a reasonably detailed description of the core technical problem your project will address (though some details will necessarily need to be filled in at design time);
the specific design forces that your high level design and low level design will need to take into account; and
an evaluation plan stating how you will determine whether or not your design and its implementation has succeeded.

Participation: every member of your team should be significantly involved in the production of this document, though how you structure the interactions within the team is up to you. For example, it's fine for one person to capture notes from a group discussion of the requirements document and write it up as long as the other team members contributed materially to the discussion that is captured.

Deadline: by 11:59pm on Friday May 29, 2009, please e-mail your team's requirements document to Prof. Gill at cdgill@cse.wustl.edu.

Your team should treat this document as a "work in progress", evolving it appropriately throughout the development cycle, and by the evaluation stage it should constitute most of your evaluation report, other than the evaluation results and analysis which you will add in that last stage of the cycle.