The Need of Documentation

Software documentation can be divided into two types:

  1. End-user documentation,
  2. Technical documentation. This article focuses on technical documentation.

Technical documentation

Technical documentation is a collection of instructions, diagrams, graphs and other documents describing the software solution in a very precise way.

Documentation should be a mandatory artefact of an ordered software. The software development team should add and update adequate documentation areas along with the software features' growth.

What should the documentation contain:

  • Supported operation system versions
  • Supported database versions
  • Used Framework versions
  • Software specification
  • Software configuration
  • Environments configuration
  • Source code documentation (API description, build process, etc.)
  • etc.

The development team should be able to recreate the whole system from the documentation alone.

The documentation should be written in the customer's language, or an universal one, like english.

Documentation versus Specification

It is a good practice to include the software specification as a part of the system documentation. Doing so allows people who read the documentation to understand the context. This is proven very helpful during software maintenance phase.

The Outdated Documentation Problem

The key aspect of documentation is its alignment with the source code. It is the most difficult problem of all - development teams usually are not used to update documentation and not keen on changing that. They sometimes don't even have any structured procedures on how the documentation should be updated.

This is the most common problem: the development team changes functionality in a rush or does not care about updating technical documentation.

Summary

In order to ensure good quality and future predictable maintenance, the customer should add a relevant item to check in the acceptance protocol.