Architectural Review

Overview

During the course of the final project, your team will complete an Architectural Peer Review. This review will focus on high-level design decisions, and will give your team an opportunity to present ideas of how the architecture of the code will be.

What it is

What it isn’t

For more tips and guidelines, check out one version of the information on SCOPE Technical Reviews given to SCOPE students in recent years.

Before the Architectural Review

The core of the architectural review is a constructive discussion between the presenting team and the audience. In order to get the most out of this conversation, you must prepare a Preparation and Framing document ahead of time.

You should identify concrete things that you want to get from your audience and make sure you structure your review to elicit the information that you are looking for. Your technical review should always start with a discussion of what you hope to get out of it.

There are many potential structures you can use for a review, and the structure you choose should be appropriate to where we are in our project cycle. Below is a list of examples, some of which are appropriate for an early stage architectural review and some of which are more appropriate for late stage architectural reviews:

Your Preparation and Framing document should have (at least) the following sections:

  1. Background and context What information about your project does the audience need to participate fully in the technical review? You should share enough to make sure your audience understands the questions you are asking, but without going into unnecessary detail.
  2. Key questions What do you want to learn from the review? What are the most important decisions your team is currently contemplating? Where might an outside perspective be most helpful? As you select key questions to ask during the review, bear in mind both the time limitations and background of your audience.
  3. Agenda for technical review session Be specific about how you plan to use your allotted time. What strategies will you use to communicate with your audience?
  4. Feedback form Create a Google form that folks in the review will use to provide you with feedback or answers to various questions you pose to your audience. Since, at least for the first review, the time you have to present will be relatively short you should expect much of the feedback you get to come from this form rather than thoughts expressed orally during your session. Please create a feedback form tailored for your architectural review and share the link no less than 2 hours before class.

It is often useful to provide some background material to your audience before the review so they’re not coming into the discussion “cold”. You may (optionally) assign the peer teams in your group a reasonable amount of “homework” (~5-10 minutes of reading) by posting on the discussion forum at least 24 hours before your technical review.

The Preparation and Framing document must be posted as Markdown to your team GitHub repository before the review takes place. You should also post any additional materials (e.g. slides, handouts, Google form) that you use during the technical review.

Day of the Architectural Review

Teams are organized into groups and announced at the start of class. The day of the review will be divided into time blocks, within which teams take turns as presenting team and audience. Both roles are equally important and you are expected to contribute fully to each.

Being a good presenter

Being a good audience member

After the Architectural Review

The best advice in the world is useless if you don’t do anything with it! After the technical review, you must prepare a Reflection and Synthesis document summarizing what you learned. This document must be posted as Markdown to your team GitHub repository before the next class after the review.

Your Reflection and Synthesis document should have (at least) the following sections:

  1. Feedback and decisions Based upon your notes from the technical review, synthesize the feedback you received addressing your key questions. How do you plan to incorporate it going forward? What new questions did you generate?

  2. Review process reflection How did the review go? Did you get answers to your key questions? Did you provide too much/too little context for your audience? Did you stick closely to your planned agenda, or did you discover new things during the discussion that made you change your plans? What could you do next time to have an even more effective technical review?

Grading rubric

The architectural review is worth 15% of your total grade.

Before: Preparation and Framing

Your team must post a Preparation and Framing document as Markdown to your team GitHub repository before the review takes place.

100%

—|—

75%
50% A significant component of the document is missing
25% The document is very unclear and missing multiple key elements
0% You didn’t turn in anything, or you clearly didn’t put any effort into creating the document

During: At the technical review session

You must attend your scheduled technical review session and contribute both as part of the presenting team and as an audience member. If you will be absent on the day of the technical review, you must contact the teaching team beforehand.

Presenting team

100%

—|—

50%
0%

Audience member

100%

—|—

50%
0%

After: Reflection and Synthesis

Your team must post a Reflection and Synthesis document as Markdown to your team GitHub repository before the next class after the review.

100%

—|—

75%
50% A significant component of the document is missing
25% The document is very unclear and missing multiple key elements
0% You didn’t turn in anything, or you clearly didn’t put any effort into creating the document