CS 240 - Intermediate Report (Design Document)

Due Fri Oct 18 at 11:59pm

Overview

The second document you will produce for your project has two main parts. The first part is a formal design specification--an accounting of how the software will be structured and developed. This artifact can be used in the future to help guide the development of the software. (Although your report won't follow the structure, you might be interested in the IEEE Standard 1016, for writing design documents). The second part is a kind of "progress report" of the state of the project so far, in which you will reflect on the current development process and how implementation might continue in the second half of the semester

This is intended to be a useful reference document---one you might refer back to as you build the system, rather than something you write and forget. The expectation is also that you will create this document as you development, rather than stopping implementation in order to write a report. Creating this document should be part of your design process, and turning it in just requiring some minor cleanup issues.

Objectives

Details

As with all documentation in this course, your report should be typeset using LaTeX---you are to turn in both the .tex source code as well as a final pdf.

The two required sections of the report are detailed below:

Design Specification

  1. This section should describe the design architecture of your module. By reading this document, I should have a strong understanding of how your system is put together. Think of it as a "walkthrough" of what your code is going to look like!
  2. Be sure to include descriptions of any design classes or submodules (including division of responsibilities), and how they interact with one another. You should specify any provided or required interfaces between submodules.
  3. Include a full UML class diagram of your implementation. Note that the class diagram need not directly correspond to the classes and objects used in your program---classes in this case should be design classes.
    • Be sure and include 3rd-party libraries (if any) in your diagram!
    • Depending on the complexity of your architecture, you may need more than one UML diagram to fully explain your design.
  4. Your document should also include a design rationale: an explanation of why you choose this particular architecture or design. Your rationale may be a separate subsection or may be mixed into your class descriptions.
  5. You must include a detailed, formal specification of any provided or required interfaces of your overall module; that is, the interfaces your team's module will use to interact with other teams' modules. You will likely want to touch base with the other teams to make sure you are all in agreement about what form these interfaces should take.
    • For example, if you will be passing JSON objects around, your document should specify that as well as the attributes of that object.
  6. You should also include some notes about the expected user interface. Although we will talk about user interface design later in the class, a simple mock-up would be helpful and appropriate at this stage. Think about how the user is going to interact with your system! Include written insights into the design of your interface.
  7. Finally, be sure and document any agreed upon design details or restrictions. For example, are there specific coding style guidelines the group has agreed to follow (and that might be informative for understanding the implementation)? Is there a particular structure to class, library, or file organization?

Project Status

  1. Your project status should be an update and reflection on what has been done so far, and what will be done in the future.
  2. Describe the current state of the implementation. What have you built so far? What works and what doesn't?
  3. Include a breakdown of team member responsibilities: who is working on what? Who is in charge of what components? Who has contributes what work?
  4. Include a complete schedule and timeline for your implementation (likely in the form of a Gantt or Activity Bar chart). The schedule should start from when you turned in your requirements document to the end of the semester and the delivery of the final project. Don't just provide the chart---also include a description of this schedule that explains and justifies the breakdown. Who will be working on what when?
    • In particular, you should focus on which components should be developed first in order to meet the integration deadlines.
  5. Include a detailed reflection on the development process so far. How has your team coordinated work, code, etc? What tools have you found, used, or rejected? What challenges have you met, and how have you overcome them? Which proceedures have been effective so far and which haven't? Are there proceedural aspects you would have done differently? Although you will only have been implementing for a few weeks, you should be getting a feel for working in a large team!
    • This is also a good time to reflect on what I can be doing to help you out---don't just write it in the report (thoug you can do that as well), but let me know if there is anything you need from me!
    • You can have individual team members write their own short reflections, or compile all your views into a single section (which often reads better, particularly if team members encountered similar problems!)

In addition to the above sections, be sure to include a cover sheet with your names and other metadata (just as with the requirements document). Also include a glossary for any technical terms, and references to any tools, libraries, or other sources you use or refer to.

Submitting

Your report should be committed to the project repository (put it in the the "docs" folder)---be sure and upload both the .tex source code and the compiled pdf. Only one copy of the team's report needs to be committed (it doesn't matter who actually pushes out the commit).

Note that there is no "revision" portion of this assignment. However, I am happy to look over early drafts (before the deadline!) and provide feedback to help you craft as strong a document as possible!

Each team member will also need to complete the second Peer Evaluation form by the paper deadline.

Grading

Your intermediate report will be graded on approximately the following criteria: