Computer Science 121 - Project #3

Introduction

Once we have clear requirements we can move on to architecture and high level design. These provide a basis for detailed construction estimates, development and testing plans. In this project, you will organize yourselves into teams and develop an architecture for a non-trivial system, and produce design specifications for a significant amount of code.

The primary goal of this project is to give you real experience with the preparation, analysis, and articulation of a system design. A secondary goal is to further develop your abilities to intelligently plan a group endeavor, and critically evaluate a completed effort.

The Problem

You may choose any type of product you want, but it should fall within a reasonable size and complexity range:

• the whole system should involve somewhere in the range of 3-12 major components.
• the components and/or modules for which you develop specifications should comprise around 150-200 lines of code per team member.
• each specified component module must include non-trivial algorithms.
• it might be interesting if there was a problem that was sufficiently complex to require the development of an investigatory prototype.

I suggest that you stay in the teams that you formed for project #2, and that you continue to work with the same concept. Most of those problems are far too large to surrender to a four week assault, but I do not ask that you prepare a high level design for an entire system. You can develop a high level architecture for the entire system, and then limit your detailed design work to a more manageable subset of its components (about 150-200 LOC per team member). You only have to do component and interface specifications for the top level, and other components in the tree-path from your high level architecture to your selected modules.

The Assignment

Assuming that you choose to continue working with the same teams and product concepts, for this project you will:

• come up with a plan (who, what, when, and how) for developing your architecture and design, creating the required work products, and dividing that work among your team members.
• develop an architectural specification for your product
• if the major architectural components are all too complex for this project (likely) develop a high level design for one of them, to resolve it into multiple sub-components. You may have to interate a few times on this step before you get down to manageable components for the detailed design.
• identify a subset of the architectural components to be assigned to individuals and designed for this project.
• derive detailed requirements (for the selected components) from the architecture and from your overall product requirements.
• write detailed specifications for the selected components.
• identify issues in these components that might (legitimately) warrant user-interface, engineering-proof-of-concept, or mine-sweeping prototyping.
• assign a module design/specification or prototyping problem to each member of the team.
  • for each design task, completely specify a module (comprising 150-200 lines of code, including all routines and any non-trivial algorithms). For each non-trivial algorithms, specify what it should do, and provide a high level description of its implementations.
  • for each U/I prototyping task, write up the goals of the prototyping effort (an important question that is blocking the design effort, and can be resolved by prototyping), and the approach to be to modeling it, then construct a working UI prototype, test-drive it with a (non-team-member) user, write up a report on that session, and then (based on that feedback) write a detailed user interface specification (not the other way around).
  • for each proof of concept prototyping task, write up the goals of the prototyping effort (a non-trivial problem, where you legitimately feel unable to proceed with the design until you have explored some issues), and the approach to be taken, construct the prototype, prove that it works, and then write up detailed design notes on how the actual product should be built.

  Each assigned module or problem will have one primary owner who will (on their own) prepare all of the specifications and code. You are, however, encouraged to ask other team members to help you with difficult problems.

  WARNING: Do not plan serious testing or conduct any design reviews of your module. These will be done in the next two projects.

• conduct a post-mortem of the entire project, and write up a report of that review.
• all work products will be versioned and maintained in subversion repositories.

If you do not wish to work with your existing teams and concepts, please contact me immediately about forming new teams and working out new product concepts. This will require you to do considerably more work, so choose this option carefully.

WARNING

This project involves a great many activties, many of which require the participation of others and are sequential in nature. It may not actually take a large number of hours, but it will take multiple weeks to complete. If you are to be successful, you will need to devise, and follow a schedule.

For any design or prototype, a non-trivial number of points will be awarded on the basis of its "worthiness". If a component is not sufficiently complex to require interesting design, or if a prototype does not answer a legitimate question, it may earn very few of these worthiness points. No points will be awarded for working prototypes of obvious mechanisms, or user interface mock-ups that do not answer legitimate questions of usability. Note that "How do you like this?" is not a legitimate usability question.

There is also a danger that you will attack components that are too difficult, do not reasonably fit together, or do not add up to the required functionality. Your design cannot include any "deus ex machina" elements (cold fusion, magic ponies, etc). For this reason, you are strongly encouraged to review your architecture and selected components with me before starting the detailed design work.

I should also mention that the next two projects will involve the module or component you design. As you choose your components, realize that you will soon be developing a test-plan for it, and preparing a formal review of your designs and test-plans.

The primary work products should all be well prepared, and should include:

1. Plan

   describing the steps that will be taken to perform this project, the division of work among team members, and the points at which results will be reviewed, combined, and turned into final work products.

2. An Architecture

   describing the major system components, the functions of each, the interfaces between them, and any interesting notes or constraints. This will probably involve one or more paragraphs of description for each component and interface.

   There should also be a brief discussion of issues that were considered, alternatives that were discarded, and the rationale that drove the adoption of this architecture.

   The architecture will be judged, not on brilliance, but merely on understandability and viability. Those are difficult enough.

3. Detailed Component Specifications

   for each component selected for elaboration. These should include all applicable requirements and interface specifications. These too should include discussions of any issues and rationale that shaped their definition, as well as any design and implementation suggestions for the designer.

4. Detailed Module Designs

   for each module selected for elaboration. These should include general specifications about the purpose of the module, and a complete specification of all classes (or routines and major data structures) it should include. For routines with non-trivial algorithms, there should also be notes to sketch out those algorithms. These specifications should be complete enough that I would feel confident to take them, sit down, and with no other specifications, start coding.

5. User Interface prototypes (if applicable)

   For any prototype user interface, there should be a note describing the questions to be answered and how a prototype can be used to answer them, a design note describing what features are to be prototyped, and how they are to be presented, a working prototype, and an evaluation based on letting a (non-team-member) user play with that prototype.

   Write up the results of that session, and then, based on this review, prepare a detailed specification for what how the user interface should work (in what ever form you think effective).

   NOTE: doing a user interface prototype, and then doing a specification may be more work than merely doing a design ... but it might enable you to earn full worthiness points for a design that would otherwise be too simple (because it was simply an assembly of widgets).

6. Mechanism prototypes (if applicable)

   For any proof-of-concept prototype constructed, there should be a design note describing the problem to be investigated and the approach to be used, and a working proof of concept program. Build and run the prototype, and write up a brief summary of exactly what testing you did to convince yourself that this approach would work.

   Based on the results of that prototyping effort, prepare a detailed design note on the way the problem should be solved in the real product and a specification for the module that would contain the engine in question. The combination of the module specification and the design note should be clear enough, to make me confident that I know how to implement the proposed mechanism.

   NOTE: doing prototype, and then doing a design may be more work than merely doing a design ... but it might enable you to earn full worthiness points for a module that would otherwise be too short (i.e. the mechanism in question is small but tricky).

7. A Post Mortem

   You, as a team, should conduct a meeting where you review and assess:

   • the partitioning of the work into tasks
   • the allocation of tasks to people
   • the architecture definition and evaluation process
   • the selection of modules to be elaborated
   • the module design process
   • the prototyping process (if any)
   • the project as an educational exercise
   One of you should write this up as a formal report.

I am not specifying formats for any of these work products, and will accept them in any combination of ASCII text, html, word, powerpoint, standard graphics formats, or even paper. Part of the exercise is for you to review what we've said about the purposes of these work products, and to figure out what information each should contain, and a way to effectively convey that information. I believe that forcing you to work this out for yourselves will have greater educational value than giving you forms to fill in.

Rules, Submissions and Grading

This is a team project, and I expect that everyone will be involved in the planning, high level architecture, component selection, and post mortem. Each person will also have a particular module or prototype for which they are entirely responsible.

Each team will be working on a different 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.

1. You may not include (uncited) material written by anyone else in a work-product for which you have primary responsibility.
2. You may not share your work products (other than for evaluation of U/I prototypes) with members of other teams.

You may do research on approaches to problems. Cite all of your sources for each work product, and explain how each source contributed to your work products.

Note that you can do any combination of module specifications, U/I prototypes, and proof-of-concept prototypes. The combination you choose will not (per se) affect your grade. Your grade will be affected by how "useful" your work is to the design process. Choose what makes sense in the context of the components you select.

All of your primary work-products will be developed, maintained, and submitted in a subversion repository, which I will create for each team. I expect the primary work products to evolve as a result of your research and meetings, and to see that evolution reflected in the svn commits and comments.

When you are done, package together:

1. the names of your team members
2. the URL for your subversion repository
3. an index of your work products, briefly enumerating and describing each, and listing specifically who did what parts of which (contribution coefficients would help).

   This will (1) be compared with the plan and (2) be the basis for the individual work portion of your grade.

If you build a prototype, we will schedule a time for you to demonstrate it for us.

And send all of these things to me in an e-mail with the subject "cs121 - proj3". If you will be submitting a project late, please notify me of this on or before the project due date. When you finally do submit it, please tell me how many of who's (3 each) slip-days you want to use.

Note that your grade will come partly from the overall quality of the team submission, and partly from the module or prototype for which you are personally responsible. So that you will know exactly what I expect to see, here is a pointer to the grading guidelines that will be used to score your submissions.