Software Technical Documentation (Overview)

Software technical documentation is an expected deliverable for software systems.

The expected audience will typically be the customer's IT or MIS department who may end up maintaining or even hosting the software system.

The technical documentation may be written in the following format:

• verbose description using natural language


• pictorial representation using modelling language
  

The level of detail may be:

• business level (for end-user)
  
• implementation level (for developer)

The following diagram depicts the above:

Examples of each are as follows (clock-wise order):

• Descriptive - Business Level documentation: use cases, process flow description
  
• Pictorial - Business Level documentation: screen flow, process flow diagram


• Pictorial - Implementation Level documentation: interaction & class diagrams depicting implementation classes


• Descriptive - Implementation Level documentation: code, data dictionary

Given that there are many ways to view the software system (logical, physical, etc), I recommend the 4+1 view by Kruchten.

The views are shown as follows:

• Use case view - Describes the architecturally significant use cases (functionality) and a high level view of the requirements of the software system.


• Logical view - Describes the design of the software system in terms of objects, modules and /or subsystems. Describes the most important classes, their organization in service packages and subsystems, and the organization of these subsystems into layers. Also describes the most important use-case realizations.


• Implementation view - Describes the physical components used to assemble the system.


• Process view - Describes the tasks (processes and threads) involved in the system's execution, their interactions and configurations. Also describes the allocation of objects and classes to tasks.


• Deployment view - Describes the various physical nodes deployed for the software system. Describes the topology and mode of communication used. Also describes the allocation of tasks (from the Process View) to the physical nodes.
  

Not all systems require every view above. For example: single processor projects will not need the deployment view, single process projects will not need the process view. For small projects, the implementation view may be eliminated.

The above views are not exhaustive. Other views may be required. For example: data view, security view, etc.

In the next few installments, I'll explain the artifacts to look for in each view.