Last update PvD
Documentation of Software
Documentation of software is a well-known problem: programmers hate it, so it is postponed until after they have finished writing the software. But making the software work correctly takes more time than expected, and then there is no time left (and the next project waits).
As a consequence, the documentation available is out-of-date and therefore not reliable, which only leaves the code ("the code is the ultimate documentation"). Any debugging or adaptation by another programmer faces the problem of trying to understand the code, which is –for any non-trivial program– not straightforward due to earlier debugging and adaptations.
A clear distintion has to be made whether the documents are part of a design process, or intended to document existing software. We start with the first.
No system of considerable size can be made without Design Documents, defining how the system is partioned into components and what each component is supposed to achieve. For software systems this is no different. Here we assume 2 levels of design documents:
Here we are only discussing software design documentation; in systems with software and hardware there will be a System Design document defining what will be done in hardware and what in software (and Hw & Sw will each have corresponding design documents).
Also, related documents, e.g. covering testing, are not discussed here.
The Top Level Design partitions the problem specified in the Requirements Specification into smaller –presumably solvable– problems commonly called modules. With that, it provides the requirements specification for each of the modules.
There is a basic tension between requirements specifications and the design activity: requirements specifications should specify what the results must be, not how to achieve that. But the design activity is just about telling how to get the specified results.
Special attention should go to all of the interfaces (they must be defined so all parties involved know where to conform to).
For performance critical systems, the expected performance (bottlenecks) should be investigated and estimated.
The Detailed Description is at least a level higher than the code itself. It specifies with what constructs the module requirements are to be met.
It is also mandatory reading for anyone who is going to work on the software (debug/modify). Preferably the Test Cases are part of (or referred to in) this documentation.
As said before, most software developpers don't like to write documentation, even if it concerns design documents: they make only a sketchy design, and consider that sufficient. But that is bad for a well-thought design, and disastrous for any later work on that software (debugging, addaptation).
Here Project Management should step in with procedures regarding documention and in particular regarding reviews. The designer/programmer should be forced to start with describing how he plans to solve his assignment.
Also, the designer/developper can be aided by having a documentation specialist and/or technical writer on the project team; he will off-load in particular the administrative work that developpers hate, enforce the applicable documentation standards and assure quality.
Contrary to the design documents, here documentation reflects what has been achieved. For documentation of software with the purpose of (re-)use, one can discern 3 levels:
Below these points are elaborated.
See also to discussion about Software Re-use.
The API is in fact a special case of an interface; for a 'conventional' interface most of the above items are applicable.
Here the software is described in large functional blocks. For each of the functional blocks the method used –the heuristics– are described. When there are options for heuristics (algorithmic methods), these should be presented with the arguments for the solution selected.
The main purpose of this type of documentation is to provide background information and understanding for anyone who is going to work on the software (e.g. to correct it, or to addapt it), or is investigating its use for another application.
For performance critical systems, the expected performance (bottlenecks) should be investigated and estimated.
The Detailed Description is at a level higher than the code itself (e.g. not algorithms but heuristics). It should explain the constructs used. It is mandatory reading for anyone who is going to work on the software. Preferably the Requirement Specification and particular Test Cases are part of this documentation.
=O=