Development documents

10.2 Development documents

Each SDLC phase produces development-oriented documentation. These documents are the statements of the increasingly complete solution for the user's needs as development proceeds. Development documentation covers the SDLC and tracks the software from the requirements that grow out of the concept exploration phase through the installation phase. This series of documents, each serving as the basis for the succeeding level, permits the producers to determine when they have completed the task and allow the testers to determine whether or not the software complies with the intended requirements.

The primary development documents are as follows:

• Requirements specification;

• Preliminary design;

• Detailed design (build to);

• Design description (as built);

• Database specification(s);

• Interface specification(s).

There are many formats for each of the basic development documents. The format for each of the basic SLC documents is less important than the content of those documents. Further, the necessity for some specific documents depends on the size and complexity of the specific project. In some cases, the required information can be provided in a higher-level document. Thus, the actual format and content specifications will be a function of the individual organization and the documentation standards that have been adopted.

The requirements document is intended to fully define the overall function to be performed or problem to be solved. It is a mandatory document, without which the project should not even be started. Until the customer or user has clearly stated what is to be provided, and all the external considerations have been identified, the producer has insufficient information with which to start work. Without a clear statement of what is wanted of the software, there is no way to determine completion or how completion is to be achieved.

Design documents, both preliminary and detailed, describe in increasing detail the method by which the problem or function is being addressed. Prior to coding, the design must be such that the coder does not need to make any "I think they meant this" decisions. After coding and testing, a final design document should be published, which is the as-built document that will be used by the software maintainers after installation.

10.2.1 Requirements specification

The requirements specification is the keystone of all software documentation. It is the statement of what the software system is to provide. It describes the problem to be solved, any restrictions or constraints on performance or environment that may be imposed, time and size restraints, hardware constraints, specific requirements levied on inputs and outputs, and any other information necessary for the complete specification of the problem or function. Other people besides the end users may levy requirements on the software. Without this complete specification of what the software is to accomplish, the producer is put in the position of having to make requirements decisions as the design progresses. This removes some of the control of the system from the customer and may result in the customer not receiving what was expected. Viewed another way, the producer is also in the position of being unable to provide anything acceptable to the customer who says, "That's not what I asked for." Appendix D shows a general format for a requirements document.

There are many ways that errors or faulty requirements creep into the requirements document. It is the role of the software quality practitioner to carefully review the requirements document, both for adherence to the format standards for the document and for the correctness of its content. The latter may pose a problem to some practitioners who do not have the appropriate expertise to adequately review the document for technical content. In those cases, outside reviewers may be used or the development group may be called on to provide a review of the requirements before they accept the development task.

In addition to being correct, requirements must meet at least five other critical criteria: They must be necessary, complete, measurable, unambiguous, and consistent (both internally and with external interfaces).

10.2.1.1 Correct

Correctness of the requirements is of primary concern, both to the customer and the producer. The description of what is wanted and the surrounding needs and constraints must be stated correctly if the development is to result in an acceptable product. The use of an equation that is not correct for the situation or addresses a government regulation incorrectly will result in a system that does not meet the needs of the customer, even though it might comply with the requirements as stated.

10.2.1.2 Traceable

Each requirement must be documented in such a way as to make clear its source or participation in the solution of the user's problem or the user need that it addresses. In addition, the requirements document should be constructed in a manner that will enhance the tracing of design and tests back to the requirements. Ultimately, each requirement has a genesis in the existing need, is supported by a solution in the software itself, and has been demonstrated to be satisfied in the testing of the software.

10.2.1.3 Necessary

A requirement that places unnecessary restrictions or demands on a software system also raises the cost in time and money at no advantage to the system. Such things as overly stringent timing, unnecessary precision in calculations, unjustifiably tight memory restrictions, excessive processing capability, and the like sometimes creep into requirements. They may sound nice or seem necessary at the outset but unnecessary requirements can cause poor development later on. The requirement for a check processing capability of 200,000 per day may sound fine, but if it is for a small bank that actually needs only to process 50,000 checks per day, it will add unnecessarily to the cost of the system and provide capability that will not be used.

10.2.1.4 Complete

Completeness may seem to be an obvious criterion for requirements, but it is no less important. When a requirements document is published that does not address the whole problem to be solved, the developer is usually in store for surprises. Either a situation will arise during design or coding that has no basis in the requirements, or the customer may ask where a desired a feature is after the producer thinks the job is done. At the very least, the producer may be put in the position of having to add or modify requirements, actions that rightfully are the responsibility of the customer. Completeness also means that nonuser requirements must be defined.

10.2.1.5 Measurable

Measurability is the key to testing. A requirement that cannot be measured cannot be demonstrated by the test program. For example, a requirement for rapid response time clearly is faulty. What exactly does rapid mean? Another example is a requirement to process multiple targets. Multiple is undefined and therefore cannot be measured or demonstrated. Requirements that cannot be measured introduce opportunities for conflict at all points within the SDLC, particularly at system demonstration and acceptance time.

A two-second response time that seems adequately rapid to the developer may be unacceptably slow in the eyes of the customer. Multiple may mean 20 to the developer but only 10 to the customer, who does not want to pay for the extra capability.

10.2.1.6 Unambiguous

Unambiguous requirements leave nothing to the imagination of the producer. There is no need to guess what the customer really meant or wanted. A requirement for a response time of no more than two seconds sounds like a good, measurable requirement. It is ambiguous, however, in that it does not state the point at which the measurement of two seconds is to begin or to end. A major source of ambiguity is such familiarity with a subject that one forgets that others may not know all the jargon or have insider information. Sometimes the requirements writer presumes that everybody knows that. Another source of ambiguity is weak wording. Requirements are to be worded in terms of the imperative verb shall. Verbs such as should or may or even will might show desire, but they do not demonstrate intent. To say that a system should compute the square root of 3 implies that it might not.

10.2.1.7 Consistent

Finally, the criterion of consistency must be considered. Requirements must be consistent within themselves and also with the world outside themselves with which they must interface. For example, the requirement in one section to process 1,000 checks per hour is inconsistent with the requirement in another section that calls for 10,000 checks in an 8-hour day. Both those requirements may be inconsistent with the outside world if the check handling machinery to be used is only capable of processing only 900 checks per hour.

10.2.2 Design specifications

Preliminary and detailed design specifications depict how each requirement will be approached and satisfied by the software. Detailed design specifications are of two types. The final design specification prior to coding can be considered the build-to design. It presents what the designers believe to be the correct solution and response to the approved requirements. The design description, which reflects the software as it was actually completed, is often referred to as the as-built design.

As was the requirements, the design must demonstrate the criteria for correctness, necessity, completeness, measurability and testability, lack of ambiguity, and consistency. Further, the design must be traceable back to the requirements. Each element of the design must be able to be shown as satisfying some part of the requirements. In return, each requirement must be able to be traced forward into the design. In that way, there is confidence that the designers have not added or omitted anything during the design process.

Regular formal and informal reviews of the design as it progresses are held to ensure that the design is not straying from the requirements. The reviews are also intended to show that the design is sound and adheres to the various criteria. The software quality practitioner plays an instrumental role in these reviews by ensuring, first of all, that they are, in fact, held. Software quality practitioners do not necessarily have to attend informal reviews, such as peer reviews, but the practitioners must be sure that the reviews are taking place and are fruitful in the search for design defects. Formal reviews may be chaired by software quality management, although some organizations find it better to have someone from the project as the chair. Software quality practitioners are responsible for attending the formal reviews and reporting on their actions. The software quality practitioner is also responsible for making sure that any and all action items resulting from the reviews are fully addressed and closed and that full reports are filed with management for any managerial action that may be necessary.

10.2.2.1 Preliminary design specification

The preliminary design (sometimes called the functional, architectural, or external design) provides the initial breakdown of the requirements into functional groups for further design efforts. Each functional group represents a major portion of the overall software system. The preliminary design must specify the approach to be taken in the performance of the function, the database requirements, and the interfaces with the other functional groups present in the system. It must also specify the interfaces with the external world, such as terminals, networks, other computers, other software systems, and so forth. Appendix E shows a sample preliminary design document format.

10.2.2.2 Build-to design

The detailed design is a specific statement of how each part of the preliminary design will be implemented in code. The detailed design is often called the build-to specification, since it is the input to the programming staff for translation into the compiler language for implementation on the target computer. This document must completely describe the design so that programmers are not in the position of having to make design decisions as they make the translation into source code. An example of a format for a detailed design document is given in Appendix F.

10.2.2.3 As-built design

A final version of the detailed design document should be prepared after the completion of the coding and testing processes. This usually is called the as-built design or design description and represents the statement of the design that was actually translated into code. It is an important document for the future maintainers of the software system. It serves as the product baseline from which all changes will be made for corrections of defects found in operation of the system and for the addition of enhancements to the software as they become necessary. Obviously, this document must be kept current and configuration managed.

10.2.3 Other documentation

The larger the system, the more documentation is appropriate. Database design and interface design documents may be needed.

Some documents are not always required as separate entities. The required content of the database design and interface design documents may be incorporated into the preliminary and detailed design documents for small or noncomplex systems.

The role of the software quality practitioner is much the same whether the database or interface discussions are part of larger documents or volumes unto themselves. Software quality practitioners must still ascertain that format and content standards are defined and met and that appropriate expression techniques are used. They also will ensure that the documentation criteria are met and that the information is consistent with itself and between documents.

There will be projects that have special documentation needs. Two that arise most often are those projects that have many, or complex interfaces, and those involving the development of, or significant interaction with, a database. When the system's interfaces, either within the software system or with the external world, are many or complicated, the preparation of interface requirements and interface design specifications should be considered. These specifications can eliminate misunderstandings of the interfaces that arise when each interface is described from one side in one document and other sides in other documents. By combining all aspects of each interface in a single place, all parties can see the full set of the interfaces' descriptions.

Database specifications are needed when the system being developed either creates or causes significant modification to the database(s). Even when a new or highly modified database is not the case, significant interaction with the existing database(s) may benefit from a specialized database document.

It should be remembered that the purpose of documentation is to describe how the user's or customer's requirements are being met and to ensure that the correct solution is being developed and implemented.