Computer Science 121 - Project 1b

Architecture Development

Fall 2007

$Id: proj_1b.m4 113 2007-10-23 20:17:23Z Mark $

Critical Dates

Plan due (midnight) 10/08/2007
Final submission due (midnight) 10/25/2007

Project Description

Introduction
Deliverables Table
Assignement Details
Grading
Rules and Submission

1. Introduction

This is the second part of a three part project. In this part, you will continue with the same teams and product concepts you had in Project 1A. Now that you have requirements, you can move on to defining an architecture to realize them. The architecture is the basis for component designs, initial construction estimates, development and testing plans.

This will complement the treatments (in the next few lectures) on:

what is architecture?
elements of a good architecture
the process of developing an architecture
modeling systems
representations of system designs

The primary goal of this project is to give you real experience with the preparation, analysis, and articulation of a system architecture. In the final part of project 1, this architecture will be subjected to review. And, as always, we hope to further develop your abilities to intelligently plan and carry out a group endeavor, and to 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 Architectural Overview 8

team work product Architectural Diagrams 4

team work product Component Specifications 8

team work product Architectural Rationale 4

team work product Architectural Issues 4

individual work product Component Design Analyses 16

team whole submission Quality of Architecture 8

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	Architectural Overview	8
team	work product	Architectural Diagrams	4
team	work product	Component Specifications	8
team	work product	Architectural Rationale	4
team	work product	Architectural Issues	4
individual	work product	Component Design Analyses	16
team	whole submission	Quality of Architecture	8
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:

come up with a plan and schedule for developing, evaluating, and documenting your architecture, creating the required work products, and dividing that work among your team members.
Standard project activities (like plan development, post-mortem, and index of work products) should be assigned to different people (than in the previous project), so that everyone gets an opportunity to do each of these tasks.
develop a high-level architecture for your product (describing the functionality of and interfaces to each major component). Note that vague aspects of your architecture, which do not seem important at this point, may become major sources of trouble in step 4.
assess the quality of the architecture (against the standards described in the first lecture on architecture). If the architecture is unsatisfactory, understand why and go back to step 2.
each member of the team will take one (or more) of the defined components and attempt a preliminary high-level design for that component (how it might be implemented).
In doing this, you will discover what the hard parts of each component are. In coming to understand those problems, you will come up with changes to the architecture that would make them easier to implement. You will also discover unforseen interactions between components. Take these lessons back to the group, enumerate them, and go back to step 2 again.
If your system has more major components than team members, some team members will have to do designs for multiple components. They will receive the average grade for the quality of their designs, but this will credit them with a larger share of work (to balance the work among team members).
It is unlikely that your product will have fewer major components than your team has members ... but if you find this to be the case, pick the largest of your components and recursively decompose it into major sub-components (with specified functionality and interfaces) until you create enough components to enable each team member to at least one preliminary design.
satisfy yourselves that each of the defined components is reasonably buildable, and that the resulting system is likely to meet all of the specified requirements.
write up a description of your architecture (intended to communicate it to people of similar experience to your own, but who have not been involved in its design):
- high level architectural overview of what the system must do, and how it will work.
- high level architectural diagram, illustrating the major components and the interfaces between them.
- preliminary specifications for each component, describing its functionality and interfaces.
- preliminary design notes on how each component could be implemented (these are not specifications, but merely an existence proof).
- rationale for this architecture, and a discussion of the issues that guided it to this form.
- a list of issues and concerns you have about this architecture.
conduct a post-mortem of the entire project, and write up a report of that review.

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.

A group can propose an architecture in about an hour, and an individual can probably consider its implications on the design of a component in a similar period of time. But architectures do not spring fully formed from your imagination. elaborating and refining an architecture takes many iterations of proposal, elaboration, and problem analysis. You should expect to have to go through 3-6 such cycles before you have a viable architecture. Make sure you schedule your work accordingly.

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 10/08/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 elaboration and evaluation of the high level architecture.
3. the preliminary designs for the individual components, and feeding the results back into the high level architecture.
4. writing up of the architecture and designs.
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:

Architectural Overview
Briefly describe the way the system is structured and how the components cooperate to achieve the requirements. If your architecture is an obvious one, a few sentences may suffice. Otherwise, you need to describe it well enough to make it obvious.
You will be graded on the basis of:
1. how clear the (conceptual) role of each component is.
2. how clear the (conceptual) interactions between the components are.
3. how clear the overall system operation is.
4. how well this prepares the reader for the remaining design documents.
Architectural Diagrams
One or more UML diagrams illustrating the major system components, their relationships to one another, and the key system interfaces.
You will be graded on the basis of:
1. are all major system components depicted.
2. are all major external interfaces depicted and characterized.
3. are all major inter-component interfaces depicted and characterized.
4. are these depictions in accordance with the more detailed design documents.
Component Specifications
For each major component, describe its functionality (in the system), its major external interfaces (to other components, and outside the system), and the requirements it must satisfy.
You will be graded on the basis of:
1. how clearly the component functionality is described.
2. how clearly the interfaces are characterized.
3. how complete the requirements are
4. how understandable the requirements are to a component implementer.
Architectural Rationale

If the architecture is obvious, explain why it is obvious. If the architecture is non-obvious, describe the issues that drove it to its current form.
You will be graded on the basis of:
1. does the rationale adequately describe the issues that drove the architecture?
2. does the rationale adequately justify the architectural responses to those issues?
3. is the rationale clear and sound?
Architectural Issues
Enumerate and briefly describe all of the major concerns you have about your final architecture. A "major concern" is anything that causes you to doubt that you would be able to successfully build a working product in a reasonable schedule.
On the off chance that your architecture is rock solid, explain (point-by-point) why if fully satisfies all requirements and all of the characteristics of a good architecture.
You will be graded on the basis of:
1. how complete your list is (are there obvious things missing)?
2. how worthy the problems are (are they trivial)?
3. how insightful your list is (how well do you understand the problems)?
Component Design Analyses
For each major component, describe how it can be implemented, and how that implementation works within the component specifications. This may require you to do a high level design for that component. It is quite likely that the first round of component design analyses will turn up problems in the specifications and may require changes to the architecture, followed by a new iteration on the component designs. If this happens, include (in this analysis) a description of the problems that were discovered and how they were addressed.
The purpose of this process is not to prepare preliminary component designs, but rather to convince ourselves that we have a reasonable set of component specifications.
You will be graded on the basis of:
1. how clear it is that your component can be implemented.
2. how reasonable the proposed implementation is.
3. how clear it is that your implementation can meet all requirements.
4. how clear it is that your component can work well within its specifications.
5. how well the design rationale was captured.
6. benefits gained from this process.
Quality of Architecture
Thus far, I have described how we will grade each individual work product. This is an overall grade for the architecture that is described by those work products.
You will be graded on the basis of:
1. how clear and simple is this architecture?
2. is the architecture a reasonable response to the enumerated requirements and issues?
3. does it exhibit good modularity and well abstracted interfaces?
4. how well have the obvious issues been analyzed and responded to?
5. is this architecture likely to be buildable, and to work?

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 1b".

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.