Documentation

The following table lists the documents that should be produced during the course, and their respective deadlines.

Document Initial version Final version
Weekly report Every week
Project description and plan w46
Requirements definition w46 w50
Design documentation w48 w01
Test specification w50
Test report w01
Project report w01

General instructions

Submitting a document means committing it in the project SVN and sending a mail to the steering group informing us that the document is ready for review, and where we can find it. For the weekly reports, committing into SVN is enough (no need to send an email). Documents should be submitted before midnight between Friday and Saturday, in the deadline week.

Before submitting, spend some effort reviewing the result to get rid of minor issues like spelling, grammar and layout. Try reading it from the steering group perspective. Does it provide enough details? Is there a clear structure and line of reasoning? Is it consistent? What grade would you give it?

Note that submission of an initial version refers to contents and not document structure and quality. For example, for the initial version of the requirements document we expect a document where the overall structure and layout is correct, although with an initial set of requirements. Perhaps some sections remains to be written, or will require significant rework at a later stage, in which case you should make a note about this.

Instructions defining what we expect each document to cover are given below.

Weekly report

Purpose: Inform the steering group of the project status, and make it clearly visible to all members of the project group as well. Also, to make explicit the plans for next week as agreed on by the project group.

Suggested template for the weekly report.

Project description and plan

Purpose: The reader should quickly get a high-level understanding of what the project is about, and some basic facts such as who the customer is and who is in the group. The document should also specify how the work will be organized, and the timeplan for the project.

Before submitting, make an internal review. Does it give a clear, detailed picture of how your project is organized, and how you plan to carry out the work?

The following items (at least) should be addressed:

Requirements definition

Purpose: Define what you are supposed to develop. This will be used initially to ensure that you have a common view of the task before you (within the group, and between the group and the customer). It will later be used to guide the development, and it is also one criteria which can be used to measure the quality of the delivered system.

Remember that requirements should focus on what to do, not how to do it. Avoid describing solutions.

The following items are probably relevant in most projects:

Design documentation

Purpose: The design document should capture important design descisions you have made in the project, and should provide a good basis for understanding the code. A possible reader (in addition to the steering group, of course) would be a new member joining the group, or someone who will maintain or evolve the system further.

The following items are relevant in most projects, but you should really think about what is important to capture (maybe some of this can be skipped, and probably additional ones should be added):

Test specification

Purpose: The test specification document should outline the overall plan for test activities to be performed in the project, motivated by the requirements. Moreover, each test should be described in detail, in principle detailed enough so that someone else could carry out the test based on these instructions.

The test specifications will differe a lot between different projects, and you have to decide what tests are relevant in your particular project and how to describe them in the best way. The following items give some ideas of what you could address:

Test report

Purpose: The test report captures and summarises the test results.

The structure of the test report should be defined together with the test specification. Then, as the test are carried out, the report is filled with information. Finally, when testing is over, the results are summarised.

This document need not be as self contained as the others. Just describe what the document is, and refer to th test specification for everything else.

Project report

Purpose: The project report should summarize the experiences of the project, both in terms of results produced and of the project work.

The following items (at least) should be addressed:


Jan Carlson ( jan.carlson@mdh.se)