Overview Document

An overview document will be required as part of most programming assignments in CS 3110. The purpose of the document is for you to convey information to the course staff about your submission, and more importantly, for you to reflect on your experience and growth as a programmer. It also gives you some practice with technical writing.

An overview document should be structured as described below. The suggested word length of each section is a guideline, not a requirement.

Format. You should format an overview document as either ASCII text (with lines at most 80 characters long) or PDF. Use good taste in formatting your document; the course staff values simplicity and readability over fancy graphic design. The typical length of an overview document should be two to four letter-sized pages, with 10–12 point font and reasonable margins. Use good judgment about what will be useful to the course staff while grading your assignment. Incomplete and excessive documentation will both be penalized.

Example. Here is an example overview document for an old CS 312 assignment. (CS 312 was the course number for CS 3110 back when course numbers had three digits.) That assignment was somewhat short and didn't involve much in the way of design decisions, so this example document is a bit on the short side, too.

Metadata

• The programming assignment title—e.g., "Assignment 2: Adventure."
• The names and netids of all students in the group submitting the assignment.

Summary (100–300 words)

Summarize the most noteworthy aspects of the rest of your overview. Anything you mention here should be described in more detail later in the document. You might include:

• Which parts of the assignment were the most challenging.
• Interesting design decisions that you made.
• Major issues that you ran into while designing, implementing, or testing your program.
• Known problems with your implementation, such as missing functionality or bugs.

Design, Implementation, and Testing (150–1000 words)

Discuss how you created a program that satisfies the assignment specification. This includes topics such as:

• Important data types you developed, and how they represent information needed by the assignment.
• Important helper functions or groups thereof you developed to implement required functions, and how they are used.
• Data structures you developed yourself or used from the standard library.
• Tradeoffs you made between simplicity of code and efficiency of execution.
• The strategy you used—e.g., top-down, bottom-up, test-driven, ...?
• Why you have confidence that your test cases demonstrate the correctness of your implementation.
• Any kinds of testing you did other than OUnit.
• How you integrated testing into your development process.
• Any challenges you encountered and how you overcame them.

Your job is to convince the course staff that you thought carefully about the construction of your program.

Division of labor (1–100 words)

If the assignment is being done with partners or with a team, explain how you divided up the work among the team members, and who contributed which major pieces of the final submission.

Known problems (1–500 words)

Detail any known problems with your submission. It's better to tell the graders about them up front than for the graders to discover them independently. Are there bugs in your program? Missing functionality? Incorrect specifications? Incorrect documentation in the code? Let us know.

Comments (1–200 words)

Express your opinions about the assignment. This section of the overview document will not be graded, but it can earn good karma. You might address such questions as:

• How much time did you spend on the assignment? How was it divided between designing, coding, and testing?
• What advice should we have given you before you started?
• What was surprising about the assignment?
• What was hard about the assignment?
• What did you like or dislike about the assignment?
• What would you change about the assignment?