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 straight­forward 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.

Making Software Design Documents

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: 

  1. Top Level Design
    The document describing how the whole software system is partioned into components and what each of these components is supposed to do.
    For very large systems there can be multiple subsystems, each with a Top Level Design document (i.e. more than 2 levels).
  2. Detailed Design
    Describing the design of an individual component.

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.

Top Level Design

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 activityrequirements 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.

Detailed Design

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.

How to get acceptable Design Documents

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.

Documentation of Existing Software

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:

  1. API/Interface description
    Documentation how to apply the software (module/routine/…);
  2. High-level description
    Provides a high-level description of the algorithm (i.e. the 'top-level' description, 'heuristics');
  3. Detailed description
    Provides an in-depth description of the algorithm (a level higher than the code level).

Below these points are elaborated.
See also to discussion about Software Re-use.

API Description

The Application Programming Interface describes how to use this piece of software (module, procedure, routine, package, class, …):

The API is in fact a special case of an interface;  for a 'conventional' interface most of the above items are applicable.

High-level Description

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.

Detailed Description

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.