CMSC 424 Project Reports

Time-stamp: "2001-12-03 17:59:21 chaw"

The main purpose of the intermediate project reports is helping you get some early feedback from me so that your final project demo and report are improved. A secondary (but important) purpose is to make sure you can document your work properly. While the intermediate reports are not worth much in terms of percentage of your grade, please take them seriously.

If any of the following instructions are unclear, please ask for clarifications in class or on the newsgroup. You must make sure you understand and follow these instructions carefully.

Submission

Reports should be submitted using anonymous FTP upload to ftp.cs.umd.edu in directory /incoming/cmsc424-0101. File names should be of the form groupname-prX-NNNN.pdf, where groupname is the (short!) name you picked for your group, X is the project report number, and NNNN is some 4-digit number of your choice. For example, if your group is called FooCoders, your first project report submission would be named FooCoders-pr1-1984.pdf (where 1984 is chosen arbitrarily). Please make sure you are consistent with the group name. For example, don't use FooCoders for one submission, fooCoders for another, and foo_coders for yet another. If you need to resubmit, simply pick another 4-digit number and upload another file following these conventions. I will grade (only) the most recent file uploaded before the deadline. Before uploading any file, you should make sure that it can be viewed using the acroread program on the detective cluster machines. If your submission generates errors in this process or otherwise fails this test, you will get no credit for it, so please be careful.

Presentation and Formatting:

Your report should be well-written, a term which I hopefully do not need to explain much. In addition to the the basics of grammar, punctuation, and spelling, you should make sure the report is well organized and that ideas are presented in a clear and logical manner. Avoid redundancy and verbosity.

Your report should use a 12-point, serif (*not* sans serif) font (e.g., Times Roman) with at least 1-inch margins on all sides. Make sure all figures are clear and well-drawn. (While a smaller font is sometimes excusable in figures, make sure everything is legible.) Word and/or page limits are strict. Figures contribute to the word-count an amount equal to the number of words in the figure. The first page of your report should include appropriate title and identifying information (group name and group members). Do not use a separate title page or cover page.

In each report submission, include all previous report submissions in an appendix. You should also include a section in each report detailing how you have addressed (or plan to address) any comments I may have made on your earlier reports. You are also free to include additional appendices containing information you believe to be useful to the reader. However, like all appendices, the material in such appendices should not be required to understand the report. That is, you should not assume that the reader will read the appendices. The appendices do not contribute to the page or word limit.

PR1

The most important parts of this report are the choice of group members and the choice of a suitable application. Please make sure to follow the Project Guidelines. You will not be allowed to modify your group unless all affected parties agree (something that would surprise me greatly if it were to ever occur). You can modify your application but, based on experience, the more (and the later) you do so, the lower your chances of producing a good project. Maximum length is two pages. Points to cover:

Group name: short and sweet!
Group members: For each member, include full name (as registered), preferred name, major, and year. Do not include SSNs; we'll try to not be numbers in this class.
A brief description of your proposed application from the end-user point-of-view. (How would you describe your proposed work to a potential, non-technical customer?)
A brief description of your implementation plans. You may wish to include a rough system architecture. Mention the programming languages, database systems (e.g., Oracle, PostgreSQL), and major libraries or components (e.g., Apache, Jserv) that you plan to use. (How would you describe your work to a classmate or other database-savvy person?)
Progress report: Outline what you have done so far and what you plan to do in the next 2-3 weeks. Try to set up some milestones for yourself.

PR2

Maximum length is 10 pages. Points to cover:

Any revisions to your project description or implementation plans.
Conceptual (ER) model for your database application. Please make sure that you follow the standard conventions as described in the textbook and in class. Any additional features that you need should be included as annotations. Try to include as many constraints as you can (as annotations). Include explanations for any constraints that are not obvious. (For example, if some constraint is the result of your design decision to allow at most one shopping cart per registered user at any time, make sure you explain this reason.) Remember that the ER diagram is a design tool and your work will be evaluated for good design. Simply submitting a syntactically correct diagram will not get you very far if the design is poor (or poorly explained). Feel free to include English explanations as needed in the main body of your report.
Logical model (relational) corresponding to the above. Again, explain any features of the translation that are not obvious (i.e., that need something in addition to a mechanical application of the process discussed in class).
Partial physical model: Include create table statements that illustrate the attribute types. Explain nonobvious design choices (e.g., if you use an integer type instead of a date type for date-of-sale).
Progress report: Outline what you have done so far and what you plan to do in the next 2-3 weeks. Try to set up some milestones for yourself.
(Reminder) Make sure you include the information each report is supposed to contain. (See above.)

Final Report

The final report consists of the following parts. Please note that, except for the first part, there is no limit (neither lower nor upper) on length. You should not feel the pressure to write a certain number of pages. For example, you don't need to write 10 pages of user documentation to get a good score. If you can say all that needs to be said in five pages, it's fine!

Summary of work: This part should be no longer than 10 pages (strict limit, includes figures, but not appendices). It should include a clear description of your application and a high-level description of the functionality you implement. This part is your chance to make sure you get credit for the parts of your project work that may not be obvious. Be sure to highlight the interesting, difficult, cool, or otherwise noteworthy parts of your project.
User documentation: This part is what you would include with your application if you were shipping it as a product. Note that by user, we mean the person setting up your application, not the end user. (For example, if you built an online bookstore application, the user here denotes the person working for the bookstore, charged with setting up the Web site, not the person buying books.) It should include a description of how your application works (major modules, processes, flow of control and data, etc.). There is no fixed page limit for this part; 10 pages is typical.
Developer documentation: This part should contain a detailed description of your implementation that would be useful to someone interested in extending or modifying it (but that is not needed by someone interested in only using it as-is). For example, you should mention here how additional functionality could be added, or how something could be implemented in a more efficient or easier manner. Do not shy away from pointing out problems in the current implementation. You will not lose points for it. In fact, if you clearly describe why something you implemented is not great, and how it can be improved, you'll get more credit. There is no fixed page limit for this part; 10 pages is typical.
Appendices: Include previous project reports, with my comments. (Don't worry if your application has changed substantially; you won't lose points for it.) You may also include here anything else that doesn't fit elsewhere.

The above four-part report should be uploaded to the FTP site as a PDF file with a suitable name (groupname-pr3-NNNN.pdf, as described earlier).

In addition, you should upload all source code as a tarred, gzipped file. Use a filename of the form groupname-src-NNNN.tar.gz (e.g., superSQL-src-8897.tar.gz). You should include a README file that describes the files in your submission and indicates how to compile them and set up your application. (As a simple test, a classmate who reads your project report and the README file should be able to set up your application.) You should include all code (and HTML pages and scripts) written by your group. Do not include compiled code and libraries. Instead, indicate how to obtain and set up the libraries. (For example, you can say "We use the Apache server version x.y.z, which is available at http://www.apache.org/"; do not include the Apache distribution!) You should include a small sample dataset (no larger than 10 MB, smaller is OK) so that someone setting up your application can test it easily. You should also include any icons needed to get your application running (e.g., logo for a online store, image of a "for sale" button). Although (unlike the programming homeworks), we do not require that your submission compile with a single make command, you are required to provide enough detail to enable someone else to set up your application, so please check to make sure you've included all the necessary files and instructions.

All the above material is due before 5:00pm on Tuesday, 11th December 2001. You are free to make changes to your code after you upload it on this date, but you will need to upload a final version of the code before your demo time.