Computer Science 121 - Project 1a

Requirements Development

Fall 2007

$Id: proj_1a.m4 116 2007-10-23 20:46:56Z Mark $

Critical Dates

Plan due (midnight) 09/10/2007
Final submission due (midnight) 10/02/2007

Project Description

Introduction
Deliverables Table
Assignement Details
Grading
Rules and Submission

1. Introduction

This is the first part of a three-part project, in which you will have the opportunity to define and design a significant software product. This project will also start your introduction to formal project management skills.

In the lecture on basic project skills we will discuss:

breaking up large projects into sub-tasks
scheduling the performance of those sub-tasks
partitioning work among team members
monitoring and managing progress
reviewing and learning lessons from past projects

In the lecture on requirements we will discuss:

the criticality of a good product definition
the characteristics of good requirements
the process for developing initial requirements
the process for getting requirements from customers

In this, the first sub-project, you will organize yourselves into teams, and develop requirements for a new product.

The primary goal of this project is to give you real experience with the major activities associated with the creation of a product concept, and the development, qualification, and prioritizing of requirements. A secondary goal is to develop your abilities to intelligently plan a group endeavor, effectively manage it, and critically evaluate the completed effort.

2. Deliverables

The graded deliverables for this project are summarized in the following table. All are described in greater detail in the assignment descriptions and grading criteria.

Type Basis Description Value

team work product Index of Work Products 2

team work product Work Plan 5

team work product Competitive Research Report 4

team work product Initial Proposed Functionality 4

team work product Initial Concept Presentation 8

team methodology Customer Requirements Gathering 16

team work product Report from User Requirements Gathering 6

team work product Requirements Analysis 8

team work product Product Proposal to Mangement 6

team work product Post Mortem Analysis 8

team methodology Use of Version Control 4

team methodology Planning and Management 4

individual work product Quality of Individual Work 15

individual methodology Share of Work 5

individual methodology Schedule Adherence 5

Type	Basis	Description	Value
team	work product	Index of Work Products	2
team	work product	Work Plan	5
team	work product	Competitive Research Report	4
team	work product	Initial Proposed Functionality	4
team	work product	Initial Concept Presentation	8
team	methodology	Customer Requirements Gathering	16
team	work product	Report from User Requirements Gathering	6
team	work product	Requirements Analysis	8
team	work product	Product Proposal to Mangement	6
team	work product	Post Mortem Analysis	8
team	methodology	Use of Version Control	4
team	methodology	Planning and Management	4
individual	work product	Quality of Individual Work	15
individual	methodology	Share of Work	5
individual	methodology	Schedule Adherence	5

3. Assignment

For this project you will:

organize yourselves into 3-5 person teams (4 is a very good number).
come up with a general concept for a product.
discuss the concept with me and get approval (to ensure it is one where you can do well, and that it differs from what other teams are doing).
I will, at this point, create a subversion repository for your team.
come up with a plan and schedule for developing your requirements, creating the required work products, and dividing that work among your team members.
research existing products in your area, and write up a brief report on the current state of the art.
identify a feature set, including improvements over existing products.
write a product description, describing your product, and explaining why it would be valuable.
identify your potential users, dividing them into sub-classes if applicable, and describe the ways in which they would use the product.
organize this into a proposal
schedule a meeting with a group of class-mates who can review your proposal (as potential consumers).
conduct the review meeting where you
1. present your concept
2. gather their feedback on the concept
3. gather their requirements
4. gather their feedback on the requirements you already have
5. gather any other comments or suggestions
assign a confidence (that you have correctly understood and captured it, and it is unlikely to change) to each requirement.
reconcile conflicts in the resulting requirements, and rewrite them in a clear final form.
assign a value and difficult to each requirement (feel free to also note how confident you are about these assessments).
use the confidence, value and difficulty to prioritize and order your requirements (high confidence/value and low cost at the top, low confidence/value and high cost at the bottom.
divide the ranked requirements into must have, should have, and defer.
write up a final product proposal (updated on the basis of the above interviews and analysis) to sell your concept to management, and give engineering a basis for estimating the cost of completion.
conduct a post-mortem of the entire project, and write up a report of that review.

The Product

You may choose any type of product you want, a new product, or an improved version of an existing product. You will not be graded on the type of product you choose ... but you should be aware that some choices are better than others:

If you choose a product for which it is difficult to do competitive research, or to develop high quality requirements, you risk earning poor scores for these parts of the assignment.
If you choose a product where research would involve purchasing equipment and/or spending a great deal of time experimenting with existing products, you will be unable to complete your research within the assigned time.
If you choose a product for which the definition and requirements are trivial, you may find it difficult to earn points for the development of these.
If you choose a product that your class-mates will be unable to intelligently comment on, you may have a hard time getting value out of your validation/elicitation review, and risk earning poor scores for that process.
If you choose a product whose implementation is likely to be too simple, you may not be unable to earn full credit on the next part of this project (architectural design).
You are going to be spending a great deal of time on this project, so I suggest that you pick a domain or problem that you find exciting.

WARNING

This project involves a great many activities, most of which require the participation of others and are sequential in nature (one task cannot be started until other tasks are completed). If you are to be successful, you will need to devise, and follow a schedule that spreads this work out over the entire alloted time.

4.Grading

This is a team project, and most of your individual grades will be determined by the quality of the team's results. This means that all of you should be concerned about the quality of all of the work products. Some of the assigned tasks are intrinsically whole-group activities (review, architectural response, post-mortem). Many others, while in principle doable by one person, will probably have significant input from other team members.

Each major work product should have a primary author, who works up the basic organization and personally writes most of the prose. The author of a work product is expected to gather and synthesize tributary work from other team members. Note, however, that since the whole team will be graded on the quality of each work product, it is only prudent for the entire team to review any high-value work product before it is submitted.

The contributions (e.g. measured in hours) of each team member to each work product should be reflected in the index of work products, as should be the primary author of each work product. To be counted as the primary author, you must have personally written at least 2/3 of the text in the submitted work-product.

In addition to an overall team grade, a portion of each individual's grade will be determined by:

the share of the work they carried (as determined from the contribution coefficients).
the quality of the work products for which they were the primary author (as indicated in the index).
how well they were able to deliver against their commitments (as determined by comparing check-in dates with the plan of record).

4.1 General Criteria

This project requires the same general project index, plans and post-mortems that are part of every project in this class:

Index of Work Products
It should also describe, for each work product:

Where, in the repository this work product can be found.
This will tell us where to find the files we will grade. If you use (different versions of) a single file for multiple deliverables, tell us which revision number to use for each.
Who (if anyone) was the primary author (the person who composed and typed at least 2/3 of the final text). If the actual writing was divided among multiple people, then there is no primary author. (note that leading a session counts as a primary authorship).
Each team member will receive a quality of individual work score based on the average grades of the work products for which they were the primary author. It would be a very good idea to make sure that each member of the team is the primary author for at least one high-point-value work product (of which there are more than enough for everyone).
If you are not the primary author for any work product, you will earn partial credit for the quality of the work products to which you made substantial contributions.
A contribution coefficient matrix for what fraction of the total hours (for each work product or activity) were put in by each person. These should sum to 1.0.
Each team member is expected to do approximately the same amount of work. Your individual share of work grades will be based on the extent to which you carried (roughly) your fair share of the work.
Work Plan
breaking the project down into sub-tasks, and describing the interdependencies between them, and who will do which when. This could be as simple as a dozen tasks with names, dates, and simple descriptions ... but may find that a more detailed elaboration gives you a better understanding of the work to be done and how you will do it.
It is expected that this plan will be revised many times (as your understanding of the problem evolves, and you respond to unanticipated events). Feel free to update the plan (with new subversion check-ins) as often as necessary.
Your plan will be graded on the basis of:
1. Was it prepared at the beginning of the project (first version checked in by the 09/10/2007 due date).
2. Was it kept up-to-date as problems forced changes?
3. Does it reasonably spread the work over the time?
4. Does it reasonably subdivide and apportion tasks?
5. Clarity and specificity
A good plan will ensure that all work is done before the due date, but allow people a reasonable amount of slack in when they have to do each particular task. An overly agressive plan that people won't be able to achieve is no better than a realistic plan to get the work done late.
Experience has shown that vague plans are easier to create up-front, but create problems down-stream (when people turn out to have been unclear about exactly what they were supposed to do, by when, and in what form they were to deliver their output). Similarly if you do not specifically map out the dependency relationships among the tasks, you may find that your schedule is unrealistic, because it does not allow sufficient time for sequential tasks.
Management
The team will be graded, as a whole, on its ability to
1. Perform the work according to the plan.
  We will determine when work was done by looking at the dates of the final subversion check-ins.
2. Monitor progress and detect problems.
  Monitoring plans should be included in your project plan. Problems that come up should be discussed in your post-mortem.
3. Reasonably adjust the plan in response to problems.
  Detected problems and responses should be discussed in your post-mortem, and reflected in revisions to the plan.
Individuals will be graded on the extent to which they were able to perform their work according to the plan of record.
Version Control
Most of your deliverables will go through a series of refinements. The importance of having key work products under version control has been discussed in class. In keeping with this, I will insist that all work products be delivered in subversion repositories. This is not merely a matter of perfunctory form. You will be graded on:
- all work products are under version control.
- (where practical) all documents have version ID strings.
- successive versions were check-in as they evolved.
- each check-in was accompanied by meaningful comments.
The history is important because we will review successive versions to see how your understanding of problems evolved. It is critical that you check in work as soon as it is completed, because we will use the check-in dates to determine whether or not tasks were completed on schedule.
Your team will be working in this repository for many projects. It will contain plans, notes, intermediate products, and final deliverables. Give some thought to how you want to organize the directories in your repository. This is another very practical project skill.
Post Mortem Analysis
This project is a learning exercise, and one of the major ways we learn is by analyzing past mistakes. You will, as a team, review all aspects of this project. One of you will then summarize that process into a post-mortem analysis report.
You will be graded on the basis of how insightful your analysis of each of these areas is, and your ability to derive useful lessons from those experiences. The report should specifically address:
1. the planning and management of this project
2. the concept definition, research, and brainstorming activities
3. the customer requirements elicitation session
4. the requirements analysis and final proposal
5. the project as an educational exercise
  This is where you assess how well I have done in defining, assigning, and managing a useful educational exercise.

4.2 Project Specific Grade-ables

The project specific grade-ables for this project are:

Competitive Research Report
Do research to identify existing products in your space (or the closest existing products to a new space), their capabilities, strengths, and weaknesses. Identify multiple ways in which you could significantly improve on these products. (if you cannot significantly improve on existing products, then there is no need for a new one).
You will be graded on the basis of:
1. how well you identified competing, similar or related products.
2. the clarity with which you understood and characterized their capabilities.
3. the practicality and value of your proposed improvements
There is no need for this to be any more than organized notes.
Initial Proposed Requirements
Brainstorm on your product concept and the capabilities of existing products to get ideas for what your product should do. Identify different types of users who might have different needs, and then identify capabilities, characteristics, and/or use cases for each.
You will be graded on the basis of:
1. how well you understood who your users might be
2. how well you anticipated their likely needs
3. how well you were able to capture these needs
The specific form in which you choose to represent these requirements is up to you. Basic capabilities may be best captured by simple declarative sentences. Complex or role based interactions may be best captured by use cases. Use the forms that you think best capture the requirements in question.
As you gather new requirements from customers, clarify them, validate them, reconcile conflicts, and prioritize them, I recommend that you make these changes in successive versions of a single requirements document. This will clearly show us the work you did in evolving and refining your requirements, and ensure that you receive full points for these activities.
Again, there is no need for this document to be any more than organized notes.
Initial Concept Presentation
At the beginning of your User Requirements Gathering session you will present an overview of your product concept. This can be (your choice) a brief document that they can have read beforehand, or a brief slide-show.
The purpose of this presentation is to give the interviewees some background on the type of product you are talking about, what problems you are trying to solve, general capabilities, and why it might be more compelling than existing products.
This presentation should specifically not introduce draft requirements that you might have brainstormed or gathered elsewhere. You are here to find out what they want, and telling them what you propose to build would contaminate them.
This presentation will be graded on the basis of:
1. how effectively it communicates the type of product you are trying to build.
2. how effectively it stimulates interest in the product, making them eager to provide input.
3. how effectively you avoid contaminating your audience with inappropriate information.
4. how professional an impression it leaves.
This presentation is a Haiku. You have 1-3 minutes in which to establish background and introduce a concept ... and you must do so without introducing extraneous (counter-productive) details. This is the only work product where form and style may be as important as substance. There are no points for showmanship, but presentation is a key part of effective communication, motivation, and leaving a good impression.
Customer Requirements Gathering
The process of gathering requirements is described in one of the reading assignments. You will conduct a customer requirements gathering session, which will be observed by the instructor (or TA). Your session will be evaluated on the basis of how well you were able to follow the process and accomplish all of its required steps:
1. Briefly introduce yourselves, agenda, and
2. Briefly introduce the product concept
3. Open-ended information gathering
4. New requirements gathering and clarification
5. Get their comments on previously gathered comments
  It is possible that, in the process of giving you their own requirements, the customers will actually touch on all of your own previously gathered requirents. If this is the case, when you get to that part of the agenda, specifically affirm that they have reiterated (or how they have changed) that prior input.
  This way you will be sure to get the points for this part of the exercise, even if the customer input has rendered it unnecessary.
6. Summary of key messages you have gotten today
7. Thanking them for their participation
Note that the moderator will (at least appear to) do most of the work in this session, and will be treated as the primary author for this activity. The role of scribe is also a crucial one (it is expected that the primary scribe will author the report on this session). It should be recognized, however, that these two people may be too busy with their specifically assigned responsibilities to actually think about and process what is being said in real time.
- another person will have the cycles to distill long discussions into punch-lines for the summary.
- another person may be able to keep track of points that need further clarification before we are done.
- another person can check off comments that relate to previously suggested requirements, and maintain a list of requirements that still require validation.
- another person can watch the agenda and the clock, and help the moderator keep to the agenda and make sure that nothing is missed.
It Other team members can also be adding value by attempting to distill recognize punch lines and key points. The moderator and scribe may be too busy to actually The
Report from User Requirements Gathering
One or more team members should act as scribes during the requirements gathering session. From those detailed minutes (which should be checked in to subversion) a summary report should be prepared. The summary report should compress out unimportant remarks, and distil long discussions into punch lines. It report should include:
1. when and where the session to place and who was in attendance.
2. interesting information gained during the open-ended information gathering.
3. clear statements of significant new requirements that were suggested, along with an assessment of how important each is and why.
4. significant input on previously gathered requirements, affirming, refuting, or changing them.
5. any other useful results gained from the meeting.
There is often confusion about how detailed requirements need to be. The answer lies in understanding what ther requirement actually is. If customers need a general capability and a wide range of implementations would suffice, then a summary of the key elements of that capability is all of the detail that is needed to capture the requirement. If a correct product has to carry out a specific process in precise detail, then all of those details need to be specified (or at least included by reference). Remember, we are not attempting to fully specify a product. We are merely trying to capture the necessary conditions for success.
This need not be polished for presentation, but it should be well organized, distilled and summarized. Very few people will ever go back to the raw meeting minutes, but a surprisingly large range of people will read the summary reports of such session (to learn about what customers do, think, and want).
Requirements Analysis
The characteristics of good requirements are discussed in both the reading and the lecture on requirements. Starting with your initial requirements:
1. revise them based on customer feedback (and your evolving understanding of the problem)
2. add the new requirements gathered from customers.
3. look for ambiguous requirements, and clarify them.
4. assign a value to each requirement, and justify that assignment.
5. assign a confidence to each requirement (that you have properly understood it and/or its value).
6. look for conflicting requirements, and resolve the conflicts.
7. assign a difficulty (easy, moderate, hard) to each, and justify your assignment.
8. assign a priority to each requirement, and then ladder them priority.
9. suggest a cut-off line for release 1.0, and justify why that is the right place to draw the line.
Product Proposal to Management
This is a proposal to management for why they should fund this product:
- It should include a version of the initial concept presentation, perhaps revised based on information gained in the requirements gathering and analysis processes.
- It should include competitive positioning information.
- It should include affirmations (based on customer input) that we have correctly understood the problem, and that this would indeed be a compelling product.
Form and will not factor in to the grading of this work product, but it will be evaluated in terms of how crisply (executives have notoriously brief attention spans) and effectively it achieves the above goals.

4.3 Work Product Formats

File Types

I grade for content and not style, and would prefer that you spend your time organizing your thoughts rather than formatting documents. My preferred file type for most work-products is ASCII text (with a reasonable line length).

Some deliverables may be awkward to prepare as ASCII text:

Tables
Diagrams
Slide show for presentations

If you prepare these using Microsoft Office tools, you can submit those files as your work-products. If you use other tools:

develop the work-product under subversion.
produce a pdf output of your final version.
check that final version of the output into subversion in a reports directory.
We will use the pdf to grade the work-product, and the subversion history of the original source to grade your use of version control.

The packages you submit for review, and the review report you return to the team whose product you reviewed should be in a directly readable form (e.g. pdf and/or ascii text).

Document Format

I am telling you the criteria on which I will grade submissions. I will not, however, give you samples for most of the work products I expect:

There are no points for "choosing the right layout". Work products will be graded on the basis of:
- completness ... do they contain all the required information.
- quality ... are they based on good analysis
- clarity ... how effectively do they communicate it
The purpose and content of each work product is described in both the reading and lecture. If (after those lectures) you still need me to enumerate these contents for you, I will conclude that you did not understand the material presented in the reading and lecture.
The characteristics of goodness for each work product are described in both the reading and lecture. If your work products do not have these characteristics, I will conclude that you did not understand the material presented in the reading and lecture.
If I gave you a sample, many of you would blindly turn it into a skeleton, and plug in your own data (mutatis mutandum) into to each section. In forcing you to figure out what information is needed, I am forcing you to come to a better understanding of the process, and the purposes that each work product is to serve.

I will, however, suggest a layout for your Index of Work Products. I make an exception here because:

very little creativity goes into this work-product.
a good layout makes projects much easier to grade.

5. Rules and Submissions

When you are done, create a message that includes:

the name of your team
the names of your team members
if you are using any slip days, how many from whom
the URL for your subversion repository
your index of work products

And submit all of these things to me in an e-mail with the subject "cs 121 - Project 1a".

If you will be submitting your project late, please let me know (so that I know I haven't lost your submission message).

Collaboration and Citation

This is a team project, but different individuals will have primary responsibility for different processes or work products (or different parts of a single work product or process). Each team will be working on a different type of product. You are free to talk your team members (and for that matter other teams) about the processes you are following. You may review your work products with your own team members, and revise them based on their feedback ... but ...

If you are the primary author of a work-product, you must cite the source of text you did not write (if it is more than a sentence), or any information that did not originate within your team or from your interviews.
You will be doing research to develop your product definition and requirements. I expect that many of the ideas for your product will come from this research. Cite all of your sources for each work product, and explain how each source contributed to your work products.
You may not share any of your work products (other than as required for reviews) with members of other teams.