The following table lists the deliverables that should be produced during the course, and their respective deadlines.
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. Deliverables should be submitted before midnight between Thursday and Friday, in the deadline week.
All submitted documents should have project name, group number, date, and document title on the first page.
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?
The deadline for the final product also includes the product being delivered to the client (in case your client wants a different delivery date, check wit us first so that it doesn't affect the grading) .
Instructions defining what we expect each document to cover are given below.
Purpose: The reader should quickly get a general understanding of what the project is about, and some basic facts such as who the customer is, who is in the group, and what is the timeplan for the project. The document should describe how the work will be organized. Finally, the document should also list the initial set of requirements.
The following items (at least) should be addressed:
- Introduction (who is the client, what is the project about)
- Project organization
- Project group (members, contact info, roles or responsibilities)
- Organization and communication (meetings, forms of contact, routines, how should worked hours and results be reported, configuration management)
- Planned effort per member for each week in the project (should sum up to roughly 150 hours per student, which includes all project work e.g. scheduled presentations etc.), known absences
- Deliverables, deadlines and milestones, both external (e.g. defined by the steering group) and internal (decided by the group)
- Quality assurance (any planned activities or routines for ensuring quality, both regarding the final product and other deliverables)
- Description of the system to be developed
- High level description of the domain and the problem
- Description of existing system, if the project is about extending or improving something that exists, or the context i.e., any existing or planned entities that the developed system should interact with but which will not be developed in the project (for example physical equipment, or an existing database).
- High-level description of the desired functionality, e.g., captured by a use-case diagram. Note, however, that you probably don't have enough knowledge at this point to include detailed descriptions of each use-case.
- Initial project backlog of system features to be implemented and other planned activities. Define priority/importance and estimated effort (e.g. in person-hours) for each entry in the backlog.
- If needed, you can also list additional functional or non-functional requirements that are not covered by the backlog.
Purpose: The design document should capture important design decisions you have made in the project, and should provide a good basis for understanding the implementation. 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.
Note that submission of a first version refers to contents and not document structure and quality. For the first version we still expect a document where the overall structure and layout is correct, although describing your current understanding of the design. Perhaps some sections remains to be written, or are expected to change a lot later, in which case you should make a note about this.
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 things should be added):
- Short background (you can refer to project description document for details, if you have more details there)
- High-level description of the system to be developed and the desired functionalities
- System overview, especially if the developed software is part of a larger system (e.g., describing the hardware and any equipment controlled by or providing input to the system, and detailed descriptions of interfaces to other systems or existing parts of the system not developed within the project)
- Software architecture. What does the overall decomposition of the software into modules/units/components look like (from a static and dynamic perspective, i.e., what are the units, and how do they interact)? What is the rationale (motivation) for this design? Depending on your project, you might also want to describe concerns such as major system states, persistent data, access control, synchronization and timing, error handling, security, etc. Use appropriate figures and diagrams to define and exemplify.
- Detailed software design. For each of the architectural units (or some, in case others are trivial or uninteresting), provide a detailed description of its internal design from a static and dynamic perspective i.e., what are the parts (e.g. classes) and how do they interact. Use appropriate figures and diagrams to define and exemplify. Make sure the description is consistent with the description of the architecture.
- Graphical User Interface. Describe the structure and general layout of the interface.
The implementation should be available in your svn repository folder.
Purpose: The test specification document should describe the planned test activities.
All projects must have some kind of acceptance test, which should be related to the client requirements. Depending on the nature of your project, you may also want to do usability tests, either on the final system, early prototypes or simple GUI mockups. In some cases, integration testing and/or unit testing could be relevant as well.
The test specifications will differ 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 should be addressed in some way, though:
- As always, you need some background, and references to other related documents.
- Give a high level overview of the test activities.
- For each test case, define detailed instructions how to carry out the test and how test results are measured (pass/fail and what are the criteria, letting the test subject answer a set of questions, etc.). Remember to relate the tests to the requirements, where possible. Tests should be described in detail, in principle detailed enough so that someone else could carry out the test based on these instructions.
- Include empty test report templates to be filled out during the tests. Don't forget to include fields for date and test subject.
Purpose: The project report should summarize the outcomes of the project, both in terms of results produced and experiences from the project work.
The following items (at least) should be addressed:
- Background information, and references to other related documents
- Project results
- Give an overview of the results produced in the project
- List the produced deliverables and the dates when they were finished.
- Summarize the results of the acceptance test (and other tests if you have done more). Either include the test reports in an appendix, or if they are too many or too long, explain where they can be found
- Comment on missing functionality or possibilities for improvements and extensions
- Project work
- Established organization and routines (refer to project plan and describe if there have been any changes during the project or if you have stuck to the initial plans)
- Total project effort (e.g., in person-days) and how it was distributed over different activities
- Worked hours per group member
- Distribution of work and responsibilities. Who has been involved in, and responsible for, the different activities?
- Positive experiences (for example successful routines or techniques)
- Improvement possibilities (for example, what would you do different if you were to do a similar project again?)