Software Engineering 2B03: Software Design II

Guidelines for team reports, 2B03
2003 February 20

When preparing your team reports for 2B03 please be sure to pay attention to all of the suggestions below. They are intended to help you to compose a high quality report which is easy to read and which properly reflects the work you and your team have invested in this project. Use the guidelines below as a checklist when planning, writing and proofreading your report.

1. General

Above all, your report and each of its parts should contain real substance. The message should be expressed clearly, completely and concisely. It should be easy to read your report and to understand its contents. Keep in mind that your readers will not be familiar with the details of your work. Be careful not to assume that they are. Think about your readers and make their task easy, not hard.

Remember that just before the reader starts to read your report, he or she will probably have been thinking about a completely different subject. In your introduction, you must gain the reader's attention and set the reader's mental context onto your subject.

Your report should be well written in an uncomplicated style, properly punctuated, grammatically correct and without spelling errors. Use a good dictionary as necessary, better more often than less. If you do not seem to be able to achieve good spelling otherwise, use an automatic spelling checker.

Each part of the team report should be proofread by one or more members of your team other than the author(s) of the part in question. In addition to proofreading the various parts of the team report, one or more members of the team should review the entire report for overall organization, consistency, etc.

Design and lay out your report and its various parts to look good without distracting the reader's attention from the message. Use different type sizes, fonts, etc. when (and only when) it will help the reader. Be careful not to use too many different type styles, sizes, etc., as doing so can easily distract and confuse the reader.

2. Organization and content

An old, general rule of thumb for preparing a report, oral presentation, etc. is "(1) tell 'em what you're going to say, (2) say it and (3) tell 'em what you've said". The beginning of your report should motivate the reader to read all the report (or, in the case of an oral presentation, to stay awake and pay attention to the entire talk). The end of your report should draw important conclusions and summarize the important messages which you expect the reader to remember.

Your report should contain at least the following material:

title page (include your league number, team number and a list of all team members)
table of contents
introduction to the project and the report
requirements to be satisfied by the module
the process of designing your team module
Module Guide and Usage Hierarchy
Module Interface Specification for the entire team module
Module Internal Design for the entire team module
Module Interface Specifications for submodules as appropriate
Interface Implementation Conventions (may be included in your interface specifications)
* designing and coding the several components of your team's module (Include Module Internal Designs as appropriate. Include complete source code in an appendix.) *
* inspecting (reviewing) the several components of your team's module *
* testing the several components of your team's module (include your test cases) *
complete final code for the team module (in an appendix)
inspecting your team module
testing your team module (include your test cases in an appendix)
planning, scheduling and executing the project (include a matrix showing which team members did which tasks, e.g. that John coded routine X, Fatima inspected routine Y, etc.)
team log
problems and observations about procedural and organizational aspects of performing the project
problems and observations about technical aspects of the project
lessons learned (including solutions to the problems referred to above)
summary and conclusions

* The items marked with an asterisk above are individual work units. Grades for these items will be assigned directly to the individuals submitting the reports on these work units, see the course outline. The team report should refer to these individual reports as separate documents. The individual reports should not be included with the team report. In your team report, you may wish to summarize selected important points and conclusions of the individual reports.

Your report may, but need not, be organized into sections as listed above. Include any other material as you feel is appropriate. Extensive technical detail (e.g. source code, test cases, etc.) can and typically should be placed in one or more appendices, with an appropriate summary, commentary or reference in the main body of the report. The same may apply to extensive non-technical detail (e.g. the team log).

In your specifications (MIS, MID, IIC, etc.) make sure that mathematical expressions are correct and presented in such a way that the reader can understand them easily.

The team log which you have been keeping will provide the basis for the team log in your team report. Compare your team log with the logs kept by the individual team members and correct and add missing detail to the team log in your report. You may want to include the team log and the several individual team member logs separately in your team report, especially if differences exist which cannot be resolved at the end of the project.

3. Binding

Your team and individual reports should be firmly bound to withstand repeated handling and reading by different people. The binding need not be fancy.