An email I sent with tips for writing your reports

Hi,

I'll put this up on the blog but report writing is a process in which you decide what should be included, not me; that is why writing reports, proposals and so on is difficult. I mark your work based on how good the job you did, of deciding what to include. With that stated, below is some guidance.

You should include an introduction: a summary the project and the rest of the report which follows. The project summary should not talk about NetBeans/Glassfish/Tomcat/Java but the problem and your solution. You should have this material, polish it up and use it. If you think something deserves credit, write about it, otherwise it shall not receive credit (marks).

Normally you would want a review or discussion of the important information (and sources of that information) and the different factors in the arguments for different approaches put forward which you used in your decision making processes: mainly technical, such as different techniques used in Java--such as how store information about the database connection and to create it--and the use of Javasctipt or CSS to solve problems.

You should have some kind of description of what you did.  Here it should be the design decisions in terms of: the Java code, JSP, database, HTML, CSS, page flow.  It should also include descriptions of how all the important bits work: not user instructions and definitely not a user manual, how it works technically. You should annotate small excerpts and include them as figures. Then refer and  explain what is happening in prose, referring the the figure. No image or listing (figure) should be included without an explanation. No figure should be as high as half a page, if it is it should be in an appendix.

Your report will clearly require a conclusion which says what worked, specifically what didn't where you had problems; not making excuses or whining that this or that was hard to use or understand but things which didn't work as expected once you had made the effort to understand how they should work.

You may want sections like this:

• Introduction
• Background
• Design (explanation of site map, wire frames, HTML and CSS)
• Implementation (explanation of database, Java & JavaScript)
• Conclusion

The chapters should be appropriate to your work so will differ from project to project.

Finally, the appendices, which should include diagrams which were to big to sensibly be included in the report.  Put the netbeans project on a cd and attach it.  No need to print it out.

Best regards,

Peter.