CS333 Project: Fourth (and final) Handout

Sat May 6 11:23:03 EDT 2000

This page makes minor updates to what you have to submit for your project. The main things in brief:

• If you made slides for your demo and want to include them in the package, that's fine.
• The installation instructions that you include will depend on the nature of your project: web-based projects will primarily include instructions for a developer picking up your code; stand-alone projects might include in addition end-user instructions.
• Actual installation requirements have been relaxed -- there's no way I could make all of these work on my machines.

May 9 (Dean's date): Final submission

Your final submission has to include your code, installation procedure, a web page that would induce others to use your system, an internals document describing the implementation, and a report on how things worked out and what you learned.

Here is what you should do:

Submission directory: Make a single directory for submission if you are not already working in a single directory. Be sure that your code is complete and still works when it is copied to the submission directory. We will be assessing your software somewhere else, so be sure to include all necessary files and remove all absolute file names.

• Make a directory for your submission.
• Create 3 sub-directories called doc, src and install.
• Copy all source files to src. This includes C/C++, Java, Perl, Tcl/Tk, makefiles, project files from VB or VC++, help files, icons, logos, and anything else necessary to recreate your project on a development system. Do not include other files that are created by compilation: no object files, executables, class files, etc.
• Copy all the documentation (described below) to doc.
• Copy your installation script, instructions, binaries, etc., to install.
• Create a gzipped tar file xxx.tar.gz, where xxx is the login name of the project manager, and submit it. A suitable command sequence is

  	cd project_directory
  	tar cf ../xxx.tar .
  	cd ..
  	gzip xxx.tar
  	submit 6 xxx.tar.gz
  

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" description, a single paragraph that states clearly and succinctly what your system does.
• Your 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's neat about your project. Make it short but seductive. If you want to include any of your demo-day material, like Powerpoint slides, this is the place to put it.
• 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 make them, as appropriate. State clearly the development environment (operating system, languages, compilers, etc.) where the system can be built, and the environment where it will run.

  The main part of the installation instructions is for a developer who is taking over your code. What will he or she need? Where are files to be installed? What changes have to be made in headers or makefiles or configuration scripts or search paths or web pages? Where can components be found if they are not included? All projects will need this part. If your system runs from a web page, it probably does not need anything else, since end-users will not be installing anything. If, however, your system runs stand-alone on some machine, you should also include instructions on how an end-user should install your system on his or her own machine.

• 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 your (developer) customers, who will need to maintain the code after they buy it from you. Help them understand how it's put together. Don't get mired in detail; a few pages is likely to be sufficient, and in no case should this be more than 8 pages in a normal font.
• A final report, in report.html, that describes how well the team worked in practice. How did your milestones go? What was your experience with design, interfaces, 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 too should be no more than 7-8 pages.

All documentation must be in simple HTML, GIF and JPEG that works with Netscape 4.5. It should be written in good English prose, free of spelling and grammar errors. It should be thorough but not exhaustive; the total submitted documentation should not exceed 15 printed pages.

Installation: If your code is meant to run on Unix or Linux, it should include a makefile such that the command make will make the system in the current directory. The command make clean should remove all temporary junk, like object files and executables.

If your system is meant to run on Windows, you can include a self-installing executable or a zip file that contains all the necessary files, along with any project files for the compiler you used.

In either case, if your system relies on the existence of major components like a compiler, a debugger, a source-code control system, or the like, these must be noted in the installation instructions, along with your best guess about how to get copies. You do not need to include them!

You should test your installation procedure just as you test your system, and you should inflict it on others if possible.

After having seen the remarkable variety of projects and environments that they run on, it is very unlikely that we will be able to compile and run them on our own systems, though we would like to try. Do your best on this, but do not kill yourself either. No matter what, the installation instructions should be complete and accurate enough that a sufficiently dedicated developer could in fact get your project running on a new system of the right kind with the right resources.