CS 410 Software Engineering

Spring 2000 Project Description - Part 2

This document describes the detailed responsibilities for the client and the developer for the project. A composite time-line is presented at the end.

NOTE: All documents must be submitted before 1:00pm on the date specified in each section below.

Client Responsibilities

(i) Informal requirements of project:

The client should prepare a requirements report that outlines the purpose of the project and gives a set of client requirements. Make sure the project is suitable for completion in one term. Remember that it is not a competition; do not aim to destroy the developer but give an honest set of requirements. (Points will be deducted for a project considered too easy or too difficult.) No more than 2 printed pages (if it were printed). January 28.

(ii) Interview by developer:

Respond to interview questions asked by the developer group in an attempt to clarify the requirements. January 31 - in class.

(iii) Functional specification:

The functional specification and management plan together describe the proposal from your developer. When accepted, these documents are a contract between you and your developer about what they intend to deliver. (Changes can be negotiated later and should be recorded as an appendix.) These documents are to be assessed and evaluated against actual requirements. Make sure that you are satisfied at this stage that your developer is aiming to meet your requirements as stated in the Functional Specification Report. Mark clearly on the developer's document any comments or amendments to the document. You may add up to 2 additional pages but do not add any new requirements at this stage or make the project any larger. February 14.

(iv) Management plan:

Assess and evaluate the Management Plan provided by the developer for any problems related specifically to the requirements. Mark clearly on the developer's document any questions you have about the document. February 18.

(v) Contract:

The developer will respond to your comments and/or amendments to the functional specification and the management plan within a week after receiving comments on the functional specification report. As necessary, and in communication with you, they will provide amendments to the documents. After you have seen the amendments you will be required to sign a contract with your developer. February 22.

(vi) Presentation:

A Design Walkthrough of about 30 minutes will be conducted by the developer in class, with up to 5 minutes of questions and discussion from you, the client. Everyone in your group must attend and take part. You should address any points which need clarification or for which you suggest changes. [For this effort, your group will serve more as peer programmers in the company rather than clients for this project.] March 23.

(vi) Demo:

Use the demo time to assess the system and the user manual. Everyone in the group must attend and take part. You should ensure that the demo relates closely to what has been negotiated and agreed upon in the contract. Weeks of May 1 and 8.

(vii) Evaluation:

Write a project evaluation (2-4 pages) which should include a discussion of how well the project satisfies your original requirements and what, if anything, has been added or subtracted; and the usefulness of the user manual. May 12. 


Developer Responsibilities

(i) Functional specification:

The Developers should conduct an interview of the clients to discuss the requirements report initially submitted by the clients. January 31.

Based on the requirements report specified by the client and other communication with the client, the developer must generate a Functional Specification Report (FSR). This report should explain what you are going to do for your project as opposed to how you will accomplish it. When writing this, do not assume that your client has any deep knowledge of computer science. Cost estimation is not required. September 21.

The report should be 8-10 pages. The first 2 pages should summarize the project you are working on. Give your system a name and describe what it does and who will use it. What needs will it satisfy? How will it help the users? Outline the most important features of your system. Describe the hardware your system will use and any important performance goals that it should satisfy, e.g., time or space efficiency, security, or reliability.

The next section of about 6-8 pages concerns the user interaction and will form the basis of your user manual (see part iv below). It should describe the functions that the system will perform from the point of view of the user. Cover the kinds of inputs your system expects, the actions it will take on both expected and unexpected inputs, and the types of outputs the user will see in those cases. (Points will be deducted for a poor user interface regardless of the opinion of the clients.) Include several sample transcripts of the interaction with your system. Include a glossary of all specialized terms used in the document, either computer science terms that the client may not know, or terms from the field in which you are working.

As part of your formal requirements, specify what your deliverables will be.

Important:  All formal requirements in the FSR must be testable and must be numbered for cross referencing with the Design and the Test Plan.

(ii) Management plan:

The Management Plan, of about 3-5 pages, should include a description of the development process you will use for your project.  It should define the life-cycle model you are using. It should include as estimate of the length of the project based on the COCOMO model. It should give an expanded schedule of the tasks and milestones of the project.  (This schedule should not just be the time-line that the instructor has provided.)  It should include the structure of your team and who will be responsible for which parts of the project.  It should also include a preliminary decision on your main data structures, algorithms, and implementation language and platform.

Make sure that you do not give the impression that you are promising more than you intend to deliver. Cover yourself by specifying a minimal system that you think you can complete by the end of March and the enhancements you could include if all goes well.  February 16.

(iii) Design documents:

During the design process you will focus on the parts of the design essential to producing a core system, and merely outline extensions to a more complex system. Remember, one of your major goals is to get something working by the deadline!

The main outcome of the design process is a detailed design document that is complete enough to be a reference from which any competent computer scientist can produce code and a user manual, and can carry out tests. This document will eventually evolve into the code and usually the system maintainer's guide. An intermediate goal is the overall design specification, which is a draft of the detailed design document with some of the details missing. Once the design has been written down, everyone in the group should read the entire document to make sure they understand the design. Individuals should be assigned responsibility for particular modules and should design these in more detail. Each person should review carefully at least one other person's section and all sections should be reviewed by someone other than the author. Pick the one(s) with which your module has the strongest interaction(s).

(iiia) Overall design:

The Overall Design Document (about 5-10 pages) should define the subsystem design, the classes and object design, and the message design of the project. It should include your major data abstractions and modules, focusing on the design, submodules, and error handling. Fill in as many details as possible in order to get feedback on it during the Design Walkthrough. Include sections discussing modifications and management questions, an executive summary, and a list of contents. March 23.

(iiib) Design Walkthrough:

A design review of about 30 minutes will be presented in class, with up to 5 minutes of questions and discussion from the client in. (Points will be deducted if this is not well organized or runs over time.) March 23.

(iiic) Detailed design:

The final step is then to prepare the Detailed Design Document. This document should be about 10-20 pages and should be built on top of the overall design document. (Keep both the Overview and the Detailed Design as two separate documents.)  It should include the data structures and algorithmic design for all attributes and the operations for each object (i.e., the responsibilities design). It should also provide answers to all questions brought up so far, for as many levels as possible. Write pseudo code or code outline for all modules. (This should be in terms of calls to other high-level functions and be easy to read.)  Update the sections describing coding responsibilities. Cross reference all parts of your design to the formal requirements given in the FSR.

Most of the work will be done by individuals filling in the details of their modules, but you must review the document as a whole to make sure people are using the same interface definitions and to make sure that everything has been covered and that the parts of the document hang together. April 3.

(iv) Testing plan:

Testing must be carefully planned and documented as to the order in which modules are to be integrated and the order in which the individual modules are to be completed and tested in isolation. Testing and debugging methods must be agreed on, documented, and carried out. Several stages of tests must be scheduled, and several testing procedures should be explored. Scheduling is required for unit tests, integration testing, functional testing, performance evaluation, and an acceptance test (demo). These should include practice in the techniques of walkthroughs, logic testing and input/output testing. The test and evaluation plan should contain a statement of objectives and success criteria, an integration plan, i.e., the order in which modules are to be combined, testing and evaluation methodologies, and responsibilities and schedules. You must devise a monitoring process to ensure that tests are designed and carried out on schedule, report lack of compliance to other group members, and decide on a procedure for reporting and correcting bugs. Discussions about testing should start early and continue through the design phase.

The Test Plan (about 10-15 pages) should contain an introductory section that summarizes the objectives and the monitoring, reporting and correcting procedures of your tests.  This should be followed by a discussion of the integration plan.  The remainder of the report should be a detailed list of the tests to be performed.  Each test should specify the objective and success criteria of the test, the individual group member responsible for the test, the date the test is planned for, and the date the test is run.   each test must also be cross referenced to the design and the requirements of the FSR.  Each person should be involved in at least one set of tests. You are advised to use walkthroughs regularly. April 12.

(v) User manual and test report:

The User Manual should be a self contained description of how to use your system. It should have a clear structure, a table of contents, and an index. Do not discuss any implementation details. It should contain an introduction, a section on how to use the system, error recognition and handling, a section showing a sample interaction complete with screen dumps, and a list of known bugs and deficiencies.

A paper (non-Web) Test Report showing the results of all tests described in the Test Plan should be submitted. The format of this report will be given at a later time. Along with the test report you must also submit the complete code of the project.

Test Report and Code are due: April 28.

User Manual is due: May 2.

(vi) Demonstration:

The demonstration should exhibit the best features of your system. It will be followed by questions from your client, with suggestions of input to try, and discussion. (Points will be deducted if the demo is not well organized.) To be given in weeks of May 1 and 8. 


General Instructions

1. No part will be accepted until all previous parts are completed. Points will be deducted for late assignments.

2. The group grade may be adjusted for individuals depending on their contribution to the group and their ability to work with their team members.

3. Logs and assessment reports are due February 21, April 3, and May 1. They should be emailed to the instructor and follow the instructions supplied in Part 1.

4. You will be graded on the project's Web page for design, completeness, and accessibility. All Web documents must include a title page with the following information:

5. All documents must be submitted before 1:00pm of the date specified. 

Project Time-Line

Week starting (Mon) Client
Developer
3 1/24 Requirements Report: 1/28  
4 1/31 Participate in Interview: 1/31 Conduct Interview: 1/31
5 2/7   Functional Specification Report: 2/9
6 2/14 Amendments to Spec. Report: 2/14

Comments on Management Plan: 2/18

Management Plan: 2/16

7 2/21 Sign Contract: 2/22 Sign Contract: 2/22
8 2/28    
9 3/20   Overall Design Document: 3/23

Design Walkthrough: 3/23 

10 3/27  
11 4/3   Detailed Design Document: 4/3
12 4/10   Test Plan: 4/12
13 4/17    
14 4/24   Test Report: 4/28

Code: 4/28

15 5/1   User Manual: 5/2 
Demos
16 5/8 (Project Evaluation Report: 5/12) Demos