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:

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

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.

Posting submission...