This document is under development. Expect some changes.
You are expected to provide an interesting and readable final report on your project. This report may be turned in at any point up to, and including, the date of the final. Unless you have strong arguments to the contrary, your report will be made part of the department's technical report series, so make sure that it presents a good impression of your work, your ability, and the department as a whole.
Your report should include
Write a manual that is sufficient for your audience to understand how to use your application. You may want to describe unusual features, unlabeled icons, missing parts, etc. You may put this documentation in any form or forms you deem appropriate, including guided tour or reference manual.
The audience for programmer documentation is a maintenance programmer. Obviously, your comments are the front line in documentation for other programmers. Make sure they are clean and up to date.
But you need more than comments. Imagine what a new programmer assigned to work with your code, next year, would need to know to understand your design, your class hierarchy and object inter-relationships, your error handling, your naming conventions, your makefiles, your distribution of code among files, and so forth. I suggest that you start with your design and test documents, fill them out to be more complete and up to date. Diagrams can be useful here; hand drawn diagrams (if legible) are fine.
As these comments suggest, there are three parts to the programmer documentation:
I will be depending on this documentation to understand (and grade) your code.
For a course like CS223, the process by which you constructed the application is important. I'd like a narrative report on this process that covers not just the time you spent on the project, but also how you spent that time, what difficulties you faced, how your projected schedule differed from your actual schedule, and so on and so forth.
The narrative is the "official history" of the project. It should include important decisions and how they were made; challenges that were or were not overcome during design, implementation, and testing; what the team would do differently if given the benefit of hindsight; and what lessons others should draw from your experiences.
It would be nice, but not essential, if your project narrative were sufficiently detailed that students in the next session of CS223 could use your project for one of the case studies.
Much of the text in this document is based on similar handouts by David Kotz and Thomas Cormen. John D. Stone suggested a number of additions and changes.
Disclaimer Often, these pages were created "on the fly" with little, if any, proofreading. Any or all of the information on the pages may be incorrect. Please contact me if you notice errors.
Source text last modified Mon Dec 1 12:51:30 1997.
This page generated on Mon Dec 1 12:53:12 1997 by SiteWeaver.
Contact our webmaster at email@example.com