The need for a software system often comes from a set of potential users, who may not be employed in the same company as the developers of the software system. Sometimes software development has no clearly identified customer other than the developer. Software is developed hoping that someone will buy it.
Initially developers must find out about the users’ domain and express their understanding of the problem in a form that is appropriate for the proposed development process.
If a plan-driven process is followed, early in the process developers produce a requirements specification document that identifies what the proposed software system should do and the environment in which it must work. It relates what the users want to what the developers aim to provide. This implies that there is a need to record more than just the requirements. It allows for the tracing of the history of each requirement from its origin in the problem domain, through the various intermediate activities, so that it is possible to reconstruct the significant events that led to the final operational software system.
The ability to trace the history of each requirement is known as traceability. Among other things, traceability is essential for dispute resolution (knowing what was agreed during a project), for seeing the effect later in the project of changing or deleting requirements, and for demonstrating that you have dealt with each requirement. The chosen development process will determine which events can be reconstructed and hence determine the level of traceability. It is important to recognise that the amount of documentation should be commensurate with the desired level of traceability – neither too much nor too little.
Agile approaches are sometimes identified with the demise of documentation. The agile manifesto contrasts working software with comprehensive documentation and agility has emerged as a reaction to heavy documentation as required in rigorous management methods (such as the capability maturity model).
However, agile approaches take a pragmatic approach to documentation and traceability (see Example 12). They emphasise the balance between the amount of documentation and the pay-off it brings. Heavy documentation is difficult to keep updated and is sometimes never used. Agile documentation should be simple to understand, have a well-defined purpose and should maximise the pay-off of the effort that is put into it. The involvement of stakeholders in an agile project will help determine the amount of documentation required.
An agile project has documentation in the form of user stories and tests. A user story describes some functionality required by a user, while a test is an executable form of a user story and therefore directly related to it. Tests are written before coding and are also directly related to the code produced. Changes over time can therefore be tracked through with the help of a tool that manages source code, and traceability can be preserved.
On a given project, there may be a number of deliverable documents that record your activities. You should treat your documents as part of the explanation of what is done. When you write down what you know about a problem, it helps to clarify your understanding of that problem and helps you to communicate with others and share the same mental model. Furthermore, writing and drawing helps you to explore the problem and the potential solutions.