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

Here is a description of the process.

1. The customer writes a Requirements document with input from the developer.
2. The developer writes a Functional Specification based on the Requirements and input from the customer.
3. The Requirements document is archived.
4. The developer writes a Technical Design based on the Functional Specification.
5. The developer writes the software based on the Functional Specification and Technical Design.
6. During development, the developer updates the Technical Design and (with input from the customer) the Functional Specification.
7. After development, the Functional Specification is used as a high-level reference for users and maintainers. and the Technical Design is used as a developer’s guide.

Next is a more detailed discussion of these documents.

Requirements

Requirements documentation gives a high-level view of what the project is supposed to accomplish, so can be used for time and cost estimates. Once finished, this is also used as a basis for the Functions Specification.

Requirements documentation should be written by the customer, possibly with some input from the developer. This document should be fairly short. It should not normally be updated once it has been written — once the planning has been done and the Functional Specification written and agreed, the Requirements documentation is not used any more.

Functional Specification

Functional Specification documentation shows a detailed view of what the software is supposed to do. This is its main role during development. After this, it serves as documentation for the system, useful for maintainers and even for users.

This should be detailed enough so that development could be completed based solely on the document and reasonable assumptions. But it should not include any more than this unless it is genuinely a functional requirement. For example, it should not contain implementation details — these should be in the technical documentation if anywhere. As another example, it should not normally contain detailed screen layouts, except where they really are crucial.

This documentation is normative, so it needs to be updated as requirements change during development. However, the documentation does not need to be complete, specifying everything down to the last button. This reduces the number of trivial updates to the documentation. To make this work, the developer and customer must co-operate, so the customer only pushes for changes that they really need. The developer cannot fall into the old adversarial system, saying things like “We don’t have to build that — it’s not in the spec.”

Technical Design

This is part of the software development process. As such, it should not be too detailed — low-level documentation should be included in the source code (e.g. in Javadoc documentation), where it is more useful and more likely to be kept up-to-date. Developers and maintainers use the Technical Design as a reference during development and maintenance, so it should always be kept up-to-date.

This should contain information that cannot properly go into the source code. This includes

• decisions made before coding, such as methodologies and general development and testing strategies
• specific tactics for individual modules
• coding standards

Summary

The simple documentation strategy for software projects emphasises minimal yet useful documentation for small to medium sized projects. Writing the documentation is not time-consuming, and the documents are useful both during the project and after it is finished.

Tags: projects