Report Writing

The details will be discussed in our group meetings. However, here is an outline of a Project Report. Every Project Report has to have these elements: * Cover page: Download page from the Department Web site. o Make sure you have the right version of this page, there seem to be several versions of it floating around. o Make sure you have the DATE when you are submitting the report. o Some old reports had Social Security Numbers. Make sure you do NOT have your SSN. Your report will be put on the Web for all to see. * Signature pages. * Abstract: This is a one page summary of the whole document. Write WHAT YOU DID in a way that every CS Graduate Student can understand it. * Table of Contents: Make sure this is formatted nicely. * Sections. What goes exactly in depends on the history of the project. o Introduction: What is the project about? What are we trying to do? This should be understandable to any 1st year graduate student in CS. No deep technical terms without explanation. o Previous Work: IF this is an ongoing project, then you describe what people before you did. ELSE IF this is a new project, you need to do research on the Web what other people did in this area. o YOUR Work: This is a REPORT of what WORK you did. The following has to be included: + A detailed description of all the programs you wrote. if you developed a difficult algorithm or "unusual" program, then show the algorithm or show the shortest possible piece of the program you need so that you can explain what is special about it. Explain how (or to what degree) the programs solve the problems described in the previous sections. + Explain problems that you encountered. If you solved them, explain in great detail how you solved them. If you did not solve them, this goes into a later section. + Demonstrate everything clearly with pictures (= figures). Screen shots, architecture diagrams, database schemas, ER diagrams, ontology diagrams, and whatever else you think would make your system clearer to other people. Use Tables where it might help. + There are stringent formatting rules for figures and tables. DO NOT DO THIS BY TRIAL AND ERROR. This is not a complete listing of rules, just look at previous projects. But, for a start, all figures are numbered. Figure captions are bold and come below the figure. Table captions, on the other hand, come above the table. Tables are numbered independently from figures. + Every figure has to come AFTER it is mentioned for the first time, and close to it. But it does NOT have to come IMMEDIATELY after it is mentioned. Figures and tables are "floating objects" and you put them where you have space. Do not leave any "white spaces" because you could not place a figure somewhere. Instead continue with the text. + For EVERY figure and EVERY table who have to write in the text something like: Figure [NUMBER] shows bla bla bla. Do NOT write "the next figure" or "the previous figure". The same rule applies for tables. o Conclusions: This is a brief summary (about one page) that summarizes all the work you did AGAIN. As opposed to the Abstract the Conclusions do NOT have to be understandable to everybody. You can use "big words" from the rest of the document. However, you CANNOT say "See Section 3" or something like that. o Future Work: The future work section contains (1) problems that you had that you were not able to solve and (2) advice for "the next student" working on this project what to do and where to continue. * A list of references. This has to look professional! So, get a book and look how they are doing it. There are hundred years old style rules for references. o If you write a reference for your fellow student, there is a standard format for that too. Do not invent formats. Look for examples and copy them. o Books, chapters in Conference Proceedings, Web pages, Papers in journals, etc. all have specific formatting rules. There are different standards. I prefer IEEE or APA standards. But I take anything that makes sense. + Putting LASTNAME, FIRSTINITIAL, TITLE at the beginning makes sense. + Putting FIRSTINITIAL, LASTNAME, TITLE at the beginning makes sense. + Putting TITLE, LASTNAME, FIRSTNAME does not make sense. Nobody does it. One more time, look at published books and see how they are doing it. o Every reference in the list has to be mentioned in the BODY of the proposal. For example: In the body you write "Previous work on Information Integration was reported in [3]." o The reference section does NOT have a section number. The Abstract does not have a section number. But everything in between has to have a section number. Typically there are also subsections (or even subsubsections). * Minimum length, about 30-35 pages, from cover page to references. Many people write more. * AFTER the references come (at least) two Appendices. o Appendix A: User Manual. This has to be a detailed explanation of EVERY file somebody needs to run your programs. Also include which directory (or even computer) these files are on. Explain how to compile the files, even if you think everybody in the world knows it. Think of it this way: A new student should be able to sit down with your manual and run all your programs. o Appendix B: ALL PROGRAMS. These are not just the programs that you yourself wrote, but other people's programs that you modified or improved or debugged. At the beginning of every file that you created, there should be a title with the name of the file, the date, and YOUR own name. If you just modified a file, it should contain the line MODIFIED BY followed by your name and the date. o Appendix C: (Not everybody has that). If you created a database, show the whole database. If the database is very large, add a note that it is very large and show the first 20 pages. If your result consists of files (not in a database), the same rules apply. Show each file completely. If your file is very large, show the first 20 pages. * A final word of advice. Do not embarrass yourself by handing in a document with spelling errors which even MS Word would mark. Do not embarrass yourself by handing in a document that you obviously never read yourself. Do not embarrass yourself by handing in a document that has "half sentences" that never end. Do not embarrass yourself by handing in a document where different pages are written in different font sizes, with different fonts, or with different line spacing between lines. Please. * A final final word of advice. Be consistent. This is probably the most important rule. Write things the same way in the whole document. As a famous example, I don't care if you write "web" or "Web" but write it the SAME way everywhere.