Here is a simple documentation strategy that emphasises minimal yet useful documentation for small to medium sized software projects. The goal is to ensure that writing the documentation is not too arduous, and that the documents are useful both during the project and after it is finished.

Traditionally, software development organisations deliver several documents, including Requirements, Functional Design and Technical Design. In this approach, each document is heavily dependent on the previous one. This means the documentation is often inconsistent. For example, if the FD needs to be revised, the TD may need updating too.

Part of this comes from the idea of forcing the customer to make all judgement calls. This can be slow. It’s better in many cases for the development team to make the call themselves, based on their understanding of customer requirements, and communicate this to the customer. The customer can then intervene if they really need to — and they won’t need to if the developers understand the actual requirements (as opposed to the documented requirements).

Continue reading “Simple documentation for software projects” →