CIS 120 Homework 6: Technical Writing

Important dates:

First draft due Monday, November 9th, 2009 at 11:00am (electronic submission)

Comments on first draft available by Monday, November 16th

Final draft due Wednesday, November 25th, 2009 at 11:00am (hardcopy submission, in class, together with first draft; no late period)

Introduction

The goal of this assignment is to give you some experience with a different aspect of programming: explaining the ideas behind programs, at an abstract level, in writing.

Begin by reading the rest of this document carefully.

The Assignment

In the 120 lectures this semester, we spent quite a bit of time going through the details of a linked-list implementation of the SimpleCollection interface. Another strategy we might have followed would have been to make this material a homework assignment, explaining the ideas at a high level and guiding students through a sequence of steps where they would implement all the pieces of the LinkedSimpleCollection and LinkedSimpleIterator classes, including the remove method of iterators. (We'll omit the contains method, to shorten things a little.)

Your task in this homework is to write such an assignment. That is, you will write the text of the homework assignment that we might have given to you if we had chosen to introduce the material this way.

Specifications:

The audience for your assigment is yourself and your classmates on October 22, 2009 — i.e., the day before we started discussing the linked list implementation of collections. This means, in particular, that you can assume your readers are familiar with pointer manipulation in Java (because they've done the two Adventure assignments) and that they have a solid understanding of the SimpleCollection and SimpleIterator interfaces (because they've seen the ArraySimpleCollection and ArraySimpleIterator classes). But you can't assume that they know anything at all about how a linked-list implementation should work.
Your goal is to give your readers a good learning experience — you want them to come out of your assignment with a deep appreciation of how linked collections work. This means you have to give them enough information that they can complete the assignment successfully, but also that you have to be careful not to give them too much information. In particular, if you list out step-by-step instructions for how to write each method, they'll be able to complete your assignment without learning anything at all from it.
Your assignment should not be longer than 1000 words. However, there is no minimum length requirement and no fixed "optimal length": make it precisely as long as it needs to be to get the job done. As with most writing, this is definitely a situation where longer is not better. If you dump too much text on your readers, you will either give away details of the solution that they would be better figuring out for themselves or else confuse and overwhelm them; either will detract from their learning.
There is no set structure for your assignment: you should decide on a sequence of explanations and tasks for your readers that will give them the best possible learning experience. The only rule is that, by the end of the assignment, your readers should have built a complete implementation of the SimpleCollection and SimpleIterator interfaces (minus contains), that this implementation should use the same basic linked list structure that we discussed in the lectures, and that they should come away with a firm understanding of how the whole thing works.
Your assignment should be expressed entirely in words, with no pictures or diagrams. This is a slightly artificial restriction — in a real assignment writeup, diagrams would be a good way of communicating some of the ideas — but taking away the "crutch" of the diagrams forces the writing to do its job well.
Unlike the assignments we've given this semester, your assignment won't include any JUnit tests. This means that one of your jobs is to explain to your readers what they need to do to make sure their implementation is working.

Submission Procedure

As part of this assignment, we're going to make use of a wonderful facility that we have here in the Engineering School: the Technical Writing Fellows of the Technical Communication Program.

Here's how it works:

You'll write and hand in a first draft of your assignment. Make this draft as polished as you can, so that the next phases have something to work with. If the writing fellows have to spend all their time on spelling and grammar or can't understand what you are talking about, they won't be able to help you improve the deeper aspects of your presentation.
Your first draft is due on Monday, November 9th.
Your document should in Word (.doc) format if at all possible. If you can't do .doc format, PDF is OK. Please do not submit documents in .docx format — .doc is much easier for the writing fellows to deal with. (Note that newer versions of Word use .docx by default; you have to explicitly ask for .doc format when you save the file.)
Please leave at least 1" margins so there's space for comments.
Your first draft will be evaluated by one of the technical writing fellows and returned to you with comments on Monday, November 16th.
In light of these comments (and your own re-reading of what you've done), you'll write a final draft.
Your final draft is due in class on Wednesday, November 23rd.
Submit a hardcopy of your assignment together with the marked-up first draft.
There will be no late period for this assignment.

Grading

Your grade will be based on how successful your assignment is at accomplishing its task. We'll evaluate it on multiple levels:

High-level structure and organization — how you've approached the problem of explaining this material.
Detailed flow and logic of your explanations — how easy it is to understand what you are saying at each point.
Grammar and spelling. At this stage of your career, there is no excuse for these not to be 100% perfect.

Your grade will be based on how well you succeed at all these levels on both drafts of your assignment. In addition, you will be graded on the improvements you make between your first and second drafts.

Extra Credit Variation

If you'd like to make the assignment a little more challenging, you can replace the singly-linked-list implementation that we saw in class with a doubly-linked version where each Node has both a next and a previous pointer. (Obviously, part of your task will be figuring out for yourself how this version should work.)