Project 2 - Fall 2012

Architecture and Review

Due Date1 Assignment2 Value3
Sun 10/07 Plan 5
~ Sun 10/14 Preliminary Architecture 25
~ Sun 10/21 Design Review 15
Sun 10/28 Final Architecture 25
Sun 10/28 Post-Mortem Report 10
n/a management 5
n/a individual contribution4 15

Table of Contents

  1. Introduction
  2. Major Activities and Deliverables
  3. Rules

1. Introduction

 Now that you have a well formulated idea of what your product should do, it is time to figure out how such a product can be built. This design must be elaborated and described well enough that outside reviewers can evaluate it, assess its feasibility, and identify holes in your design. This project will exercise a great many key design skills:

2. Major Activities and Deliverables

There are several major parts to this project, each of which has its own goals, processes, and deliverables:

  1. Initial Plan
    You will develop a plan for this project, dividing the work over your team members and the available time.
  2. Preliminary Architecture
    You will develop an architecture and high level component specifications for your project (probably going through many internal revisions and reviews before you have a design that works). Where critical questions exist, you will define and carry out research and prototyping efforts to answer them. Once you believe that you have a viable architecture, you will document it, and submit it for design review by another team.
  3. Review
    You will study another team's proposal, conduct a formal design review, write up a detailed report, and work the raised issues with the creating team.
  4. Revised Architectural Proposal
    You will revise your architectural proposal to address the issues raised in your design review and prepare a final proposal.
  5. Post Mortem
    You will review the processes you followed in this project to see what lessons you can learn for how to do things more effectively in the future.
  6. Project Management
    All of the above will be planned, documented, and managed.

2.1 Plan

 The development of the architecture may probably be much more difficult than you imagine, the process of describing it clearly in writing may prove extremely challenging, and you will probably discover that (after your design review) you have a great deal of non-trivial work to do to fix your design. Also, remember that design is a wicked problem: Each of these factors can cause the work to very quickly grow much larger than your initial estimates. This means you need to get budget a great deal of time for revision and rework, and get started as soon and fast as possible.

2.1.1 Deliverables

Each team will prepare a task-breakdown, identify the dependency relationships between tasks, and owners for each sub-task, assign due-dates, and schedule regular reviews of both work-products and progress (to enable adequate time to deal with the problems that will happen). A good management plan will include regular status checks, the results of which should be recorded in the plan document.

As your understanding of the problem evolves and you respond to unanticipated events, you will have to revise your plan (not merely estimates, but the work to be done). If deadlines are missed, or deliverables fail to pass review, the fact, as well as the causes and the plan to remedy them must be documented.

2.1.2 Grading

Your initial Management Plan will be graded on the basis of:

2.1.3 Submission

 Maintain your plan on github. You will surely be updating it, and we will be reviewing your history (changes and comments). When you are ready to submit them for grading, fill out the following form and e-mail it to the submission alias. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2A - Management Plan
       Plan:    https://github.com/your_repo/...
       primary author: person1

       if you have other files to submit, please include a brief
       description of each.

    Late points:
        if this submission is late, who is using up how many late points

2.2 Preliminary Architecture

 You will design and specify a set of components that is (in combination) capable of delivering your version 1.0 product functionality. It is tempting to draw some high level pictures and a brief set of descriptions and call it an architecture ... but the devil is in the details. The hard part is working out the implementation and characteristics of the architecture in sufficient detail to demonstrate that the described system is buildable and likely to work:

Recall that McConnell described design as a wicked problem, in that you may not even have a list of problems to be solved until you have designed (and discarded) a few solutions. This is a highly iterative process, and these iterations may consume a great deal of your time. Often, the best way to convince ourselves of the feasibility of an architecture is to sketch out possible implementations of each major component, looking for options and issues. Such preliminary research, design, analysis, and prototyping is an important sanity check on the viability of the proposed architecture. The goal of these investigations is not to fully design the major components, but merely to present a compelling argument for the "feasibility" of the proposed component descriptions:

You don't want your architecture to turn into a complete top-down design for the whole system. A component analysis only needs to be complete enough to convince the reviewers that the most of the likely problems have been identified, and are all likely to be solveable. Every major component should be analyzed to this "feasibility" level. Each member of the team should take ownership of the analysis for at least one major architectural component. If you have many more components than people, each person should choose at least one interesting component for thorough analysis or one interesting question to resovle through a prototyping effort.

If you have too many questions and components, it will be impossible for you to do all of the necessary design and prototyping within a few weeks. After each person has taken on a difficult component or question, you can do a more superficial job on the simpler questions and components (but note explicitly in each that you are doing so). In the unlikely situation that you have more people than interesting components, sub-divide your major components to create more pieces or find a problem that requires further analysis or prototyping.

2.2.1 Deliverables

Your architectural description should include:

This should be backed up by a set of component analyses (research, designs, analyses, prototypes, etc) that were done to establish the feasibility of implementing each major component:

You will note that, while I do describe what should be present in your architectural description (and there are two full lectures on the elements of good architecture), I am not giving you sample architectural descriptions. There are two reasons for this:

2.2.2 Grading

 This submission be graded on the basis of:

2.2.3 Submission

 When you believe your architecture to be complete, correct, and comprenensible, check in all the pieces, fill out the following form and e-mail it to the submission alias. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2B - Preliminary Architecture
       architecture: https://github.com/your_repo/...
       primary author: person1
	
       component analysis 1:  https://github.com/your_repo/...
       primary author: person1

       component analysis 2:  https://github.com/your_repo/...
       primary author: person2

	...

       if you have other files to submit, please include a brief
       description of each.

    Late points:
        if this submission is late, who is using up how many late points

2.3 Design Review

 As we refine a design, it is easy to become convinced that we have made the right decision and that our design is therefore correct. After we have done our best at refining our architecture, it is time to seek independent validation from people who haven't already bought-in to our solution.

Each team will read over another team's architectural presentation, prepare detailed notes, conduct a formal design review, produce a written report, and work with the designing team to ensure reasonable resolution of all outstanding issues. You will select a moderator, who will work with the submitting team to ensure that the package is ready for review before it is sent to the rest of your team for review. Please document any discussions between your moderator and the submitting team.

2.3.1 Deliverables

2.3.1.1 Review Notes
Prior to your review meeting, each of you (individually) will read the submitted architecture description and prepare detailed notes on all questions and concerns. These notes must be submitted at least 24 hours prior to the actual review session. They should be neat notes, describing legitimate issues clearly enough to be sent as email, and organized for discussion (e.g. in the recommended review order).
2.3.1.2 Review Meeting
Your team will conduct a formal design review of the submitted architecture. The team that submitted that architecture will be present to answer questions, but will have no other formal role in the process.
2.3.1.3 Review Report
The designated scribe for your review session will write up a report of all conclusions reached in the design review. This is specifically not "meeting minutes". Rather it is a distillation of key issues and decisions. It should be carefully written and reviewed. It must contain:
2.3.1.4 Issue Resolution
You will work with the submitting team to ensure satisfactory resolution of all issues raised at the design review, and will submit a final report on the resolution status of each issue.

2.3.2 Grading

 These submissions be graded on the basis of:

2.3.3 Submission
2.3.3.1 Study notes
When you have completed your study notes in preparation for the review, each individual should fill out the following form and e-mail it to the submission alias. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2C - Review Study Notes
       Notes: https://github.com/your_repo/...
       author: person1

       if you have other files to submit, please include a brief
       description of each.
NOTE: Late points cannot be used for this submission.
2.3.3.2 Review Meeting

Schedule your review meeting with the professor or grutor. Make sure the submitting team can get you the architectural package far enough in advance to enable you to do the required study and prepare your notes prior to the review meeting.

2.3.3.3 Review Report
When you have completed your Review Report, the scribe should fill out the following form and e-mail it to the submission alias. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2D - Review Report
       Notes: https://github.com/your_repo/...
       scribe: person1

    Late points:
        if this submission is late, who is using up how many late points
2.3.3.4 Final Issue Report
When the submitting team has addressed all issues, prepare a final report summarizing the status of all issues and then fill out the following form and e-mail it to the submission alias. Make sure you schedule this with the submitting team to allow yourself time to write up this report. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2E - Final Review Report
       Notes: https://github.com/your_repo/...
       primary author: person1

    Late points:
        if this submission is late, who is using up how many late points

2.4 Revised Architectural Proposal

 You will get considerable feedback on your initial architecture proposal from the professor, the grutor, and the team that reviews it. Based on this feedback, you should revise your architecture to address all of the must-fix issues, and as many as possible of the should-fix issues. You will be graded on these resolutions, so make sure you document all changes made and agreement from the reviewers.

2.4.1 Deliverables

2.4.1.1 Revised Architectural Proposal

This is simply a new version of the original proposal, revised based on the feedback from the graders and reviewers.

2.4.1.2 Summary of responses to raised issues

This is a summary of the issues raised and discovered since the initial architectural proposal, and the changes made to address them. It is not a formal report, but gives you the opportunity to draw our attention to the improvements you have made.

2.4.2 Grading

The revised architectural presentation will be graded on the same criteria as the initial architectural presentation (with the exception of the architectural rationale and issue understanding points). These points will be awarded for your summary of responses to raised issues document:

2.4.3 Submission

 When your final architecture and issue resolutions are done, fill out the following form and e-mail it to the submission alias. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2F - Final Architecture
       Revised Architecture: https://github.com/your_repo/...
       primary author: person1
       Summary of Issue Responses: https://github.com/your_repo/...
       primary author: person2

       if you have other files to submit, please include a brief
       description of each.

    Late points:
        if this submission is late, who is using up how many late points
...

2.8 Post-Mortem Report

 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.

2.8.1 Deliverables

A report, summarizing the key issues raised in your post-mortem, and the conclusions you came to. Your post-mortem discussion should include:

Note that if you make no mistakes, you will not be able to earn any points on the post-mortem. Fortunately, no teams have ever found it necessary to deliberately make mistakes in order to have something to analyze.

2.8.2 Grading

This report be graded on the basis of:

2.8.3 Submission

 Make sure that you have kept your management plan up-to-date, upload the notes from your post-mortem discussion to github, fill out the following form and e-mail it to the submission alias. 
    Team: name-of-your-team

    Members: person1, person2, person3, person4

    Project: 2G - Post-Mortem
       Plan:    https://github.com/your_repo/...
       primary maintainer: person1
       Report:  https://github.com/your_repo/...
       primary editor: person2

       if you have other files to submit, please include a brief
       description of each.

    Late points:
        if this submission is late, who is using up how many late points

2.9 Management

The team will be graded on how effectively they managed themselves and the work:

  1. Perform the work according to the plan.
    We will determine when work was done by looking at the dates of the final check-ins.
  2. Monitor progress and detect problems.
    Monitoring plans should be included in your project plan. Status should be reviewed regularly, and logged as updates to the project plan. Problems that come up should be recorded as updates to the project plan and 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.

3. Rules

3.1 Due Dates and Slip Days

Any assignment that is not turned in by its due date, will have its grade reduced by 10% (of its nominal value) for each late day. I understand that problems happen, and so each student is granted three slip days. A team of four students would have twelve slip days between them.

One slip-day will excuse one deliverable being late by one day. If a design is one day late, and that delays the design review by a day, then you may find that you need two slip-days. Don't make the mistake of using up your slip-days too soon, because the pressures generally get tighter later in the course.

When a team needs to use slip-days, they need to decide who's days they are using. However you decide is OK with me, but we will be tracking the slip days per student. If will be using any slip days on a deliverable, tell me in advance that you will be doing so (so that I don't nag you about whether or not I lost your submission message).

3.2 Team and Individual Grades

When we tackle big projects, we succeed or fail as a team. Consequently, the majority of the grade you earn on a team project will be based on the overall quality of the team's product. But a team can only be successful if everybody is working towards producing quality results. Thus, a non-negligible portion of your grade will be based on individual contributions:
criterion value
quality of primary authorships 5%
share of project work 5%
personal on-time performance 5%

3.3 Primary Authorship

While many activities (e.g. Post Mortem review) are fundamentally team activities, each major work product will typically have a primary author: one person who works up the basic organization, pulls together the contribution from the other team members and writes most of the prose.

The ability to organize large collections of information into a coherent narrative is an important skill, and each team members should take primary authorship for multiple work products. The quality portion of the individual contribution grade is based on the work products for which that person was the primary author (presided over a process, or wrote at least 2/3 of the text in a document).

Each work product submission must include an indication of the primary author (or authors if no individual produced 2/3 of the text). 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.

3.4 Share of Project Work

The quantification of individual contributions is an inexact process. Reports of hours-spent are sometimes unreliable, and often seem poorly correlated to results obtained. None the less, team members generally have a pretty good sense of who is working how hard and contributing how much value. At the end of each project, each member of each team should submit (by private e-mail to me) an assessment of how the overall effort was divided between the various project activities and team members. Something like:
activity fraction of total Algernon Balder Osiris
management 15% 50% 30% 20%
research 25% 00% 75% 25%
report 1 10% 10% 75% 15%
prototyping 35% 20% 15% 65%
final report 15% 50% 25% 25%

I will keep these as confidential, and average them together to get a sense of the individual contributions to each team's efforts.

3.5 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 ...

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

  2. You may not share any of your work products (other than as required for reviews) with members of other teams.