Motivation

Documentations for SW systems are useful and sometimes essentially necessary to guarantee a long time understanding of concepts. Nevertheless there are a number of drawbacks concerning the relation between documentation and program code:

• a less frequently updated documentation does not describe the state of recently changed source code
• for many programmers (and managers) it is more relevant to add features to source code than updating the belonging documentation
• code comments are a means of documenting and may also be used to extract them for automatically generated documentation. But many programmers hesitate to add and update ugly and special formatted comments. They prefer a pure and compact style of programmming where comments are widely undesirable.

Main targets for a new documentation style

• The documentation shall always reflect the current state of the SW implementation.
• Differences between code and documentation shall be automatically detectable.
• "Pollution" of the source code with comments shall be avoided

Concept

• restrict the textual descriptions to short text sections
• heavily rely on included snippets of real code, which are part of working programs (e.g. part of unit test projects)
• use for each topic a separate text file, so extension of documentation means adding an additional (short) text file
• use DoxyGen for generating the resulting document (HTML), where text sections and code snippets are combined
• within the textual descriptions use markdown syntax, which is easily readable while it also supports advanced formatting possibilities for the generated document.

Generation of documentation

Instruction and guarantee for a correct documentation status

• regularly regenerate your documentation, may be once a week, once a month or just when you have added some contents
• if references to code snippets are no longer valid you will get an error message from doxygen and you have to adjust the file reference or edit the description
• as the code snippets are part of your (test) code they always will reflect the newest state of implementation, otherwise you would get compile or runtime errors from your test project, which you have to fix anyway