COS 333: Final Submission Information

COS 333 Project: Final Submission Information

Fri May 8 17:27:23 EDT 2009

This page reiterates what you have to submit by Dean's Date, Tuesday May 12.

May 12 (Dean's date): Final submission

Everything must be submitted by 5 PM on this date, without exception.

Your final submission must include

most important: access to a working version of your system so we can test it

the code you wrote so we can see what you actually did

a web page that would induce others to use your system

an installation procedure spelled out in sufficient detail that a dedicated user or developer could move your system elsewhere

an internals document giving an overview of the implementation in enough detail that it would guide someone taking over your code

a report on how things worked out and what you learned, including things like how the project evolved from your original design, unexpected problems, advice you might give to a future COS 333 student (as in comments from previous years)
your timeline, up to date

Submission:

Collect everything for submission in one place.

Make a directory for your submission.
Copy all the documentation (described below) to this directory.
Create a sub-directory called src.
Copy all source files to src. This includes anything you created, especially source code and similar material. If you have help files, images, data, etc., put that here too (sub-directories are fine, but don't get carried away). Do not include other files that are created by compilation or downloaded from somewhere else: no object files, executables, class files, etc. This is so we don't run out of space.
Create a gzipped tar file jdoe.tar.gz, where jdoe is the login name of the project manager, and submit it as if it were Assignment 6. A suitable command sequence is
```
	cd submission_directory
	tar cf ../jdoe.tar .
	cd ..
	gzip jdoe.tar
	~cos333/bin/submit 6 jdoe.tar.gz
```

Be sure that your code is complete after it is copied to the submission directory. We will be reading through your source code to get an idea of what you did and how well it was done, so everything should be there.

Documentation:

The documentation must include the following:

A standard first page index.html that looks exactly like this one. This page must refer to the other components of the documentation as shown. It must include the "elevator speech" description, a single paragraph that states clearly and succinctly what your system does. And it must tell us how to access a working version of your project so we can experiment. This is very important, so make sure that what you tell us here is right!
Any advertising material, starting in a page called product.html: teaser web page, short product description, screen shots, tutorial sequences, etc. This is the part that explains to potential customers or users what your project does and what's neat about it. The content and format are up to you, but try to make it short and seductive. (It's better if it works with all browsers and does not require plug-ins but I'm willing to use Flash if you think it improves your product.)
Installation instructions, in a file called install.html. This must contain enough detail that a user could install the executables on a suitable system, or a developer could create them, or both, as appropriate. Think about the installation processes for some of the systems you used. There's often a file called INSTALL that explains what to do. Yours might be analogous. This is also the place where you implicitly acknowledge the software systems that you used but did not create. Do not include them! We will not try to recreate your system, but we want to see the components and process spelled out carefully enough that we could imagine doing it if so motivated. A single page might well be enough here.
The installation part is mostly to make sure that all the files you created are included and there's enough of a roadmap that someone really dedicated (not me) could get it installed on a new system; it's partly a way to encourage you to be sure that you've included everything that's needed, either directly because it's code you wrote, or by reference if it's a big package like MySQL or some Java class library. One way to be sure that you have provided enough code and supporting info is to take your own installation package and move it to another machine and install it yourself as if you were a new developer. That's almost always a good check, and if that works, it should be more than enough for us too.
Internals documentation, in a file called internals.html. This should describe the internal structure of the software. Imagine that you are writing this document for developers who will be maintaining the code after you hand it over. Help them understand how it's put together. If you were in that position, what would your like to have? Don't get mired in detail; half a dozen pages is likely to be more than sufficient.
The internals part is mostly to get you to think about an orderly and compact description of the components and their interfaces, striking a balance between too much detail and not enough.
A final report, in report.html, that describes how well the project worked out. How good was your original planning? How did your milestones go? What was your experience with design, interfaces, languages, systems, testing, etc.? What surprises, pleasant or otherwise, did you encounter on the way? What choices did you make that worked out well or badly? What would you like to do if there were more time? How would you do things differently next time? Imagine that you are writing this document for your (friendly!) boss or professor and want to explain what you learned that could be applied to the next project. This report is the most important component of the written part, so put some effort into it. A page is too short for this part.
Some groups present a single unified report, synthesized from the thoughts of all group members. Other groups prefer to write separate pieces of the report, since they focused on different project components and learned different things. Either style or some mixture is fine, but try to avoid too much repetition and "this was really interesting and we learned a lot."
Your timeline, in timeline.html. Like documentation, this was supposed to be produced along the way.
You can include your demo material, e.g., a Powerpoint presentation, here if you like.

All documentation should be written in good English, and be free of spelling and grammar errors. It should be thorough but not exhaustive; the total submitted documentation should not likely exceed 15 printed pages. I am particularly interested in thoughtful and interesting reports, so don't skimp on this part.

A working system:

We will be experimenting with your system starting on Dean's Date, so you must provide us with some kind of access to a running version. If the system is web-based, make sure it's up and running and we have access to whatever passwords and other controls are necessary to play with the system; that includes administrative rights if part of the functionality involves administration. (We will try very hard not to break things by inadvertent use of administrative rights.)

You should test carefully to ensure that someone not in your group can exercise all aspects of the system.

If your system is meant to run on an iPhone or Android, I will need instructions on how to load it on a (borrowed) phone, though if I can run on the corresponding simulator, that might be enough. You should make it clear to me and the TAs how we can do this.

If you system runs standalone on Windows or a Mac, there should be an executable or a .dmg or whatever that we can install on our own machines.

It will be a great help if you follow these directions and try to make it easy for us to look at and play with your project. If things go well, we tend to be happy; if things go badly, we get grumpy. Happy graders tend to give better grades.

Important: We will be experimenting with your system starting May 12, so please make sure that it is up and stays running through May 18. Someone has to monitor its behavior, and also respond promptly to mail in case we have trouble. Thanks.