Software Documentation¶

The documentation of a piece of software can be a separate document alongside the source code or included into the code itself. The documentation is a description of the software, how it works, how it was implemented and how it should be used. Foe a software developer, the documentation should tell at least:

The specification of the software, i.e. the requirements of the software
The architecture of the software
Code level documentation: interfaces, code comments
Implementation hisotry: version control log
User manual
...

Documentation always has a target audience. Documentation can be targeted to people inside the project of to external people. A good documentation take sthe target audience into account and at the same time is regardless of the target audience:

clear
concise
comprehensive
contains all necessary information
contains nothing unnecessary

Working Software over Comprehensive Documentation¶

In agile software development agile manifestosta the emphasis is on the importance of the software over documentation. This does not indicate that documentation is futile. The emphasis is, however, that the documentation covers on ly things that are relevant to the different stakeholders. No documentation is done for documentation's sake.

Software documentation comprises several data sources. For example:

class diagram
README file
Change log
Interface documentation
Vercion control logs
User manual

are considered as a part of the documentation.

Documenting the Class Project¶

The target audience for the class project documentation is the team itself, the course personnel grading the project and the group conducting the peer review. Each project needs to contain under version control a directory Documentation containing an up to date documentation of the project. As a whole the documentation contains:

Versioncontrol logs
Code comments including possible interface documentation of own classes
PDF-document under the directory Documentation

The PDF-document decribes:

the structure of the part of the software implemented by the course team. A clear hand drawn diagram is perfectly fine.
reposnibilities of the key classes
project functionality, i.e. how the objects in the project together implement the software
those classes implemented by the team containing pre and post conditions.
each extra feature clearly described
the agreed and actual division of work
a short user manual including a description of the game i.e. the rules of the game
known bugs or missing features

Note especially that the documentation should help the peer review team to get an overall picture of the project in order to make comparing the implementations possible.

The PDF-document should not exceed five (5) pages.