Functional Documentation for Computer Systems Engineering

(Revised Version of CRL Report No. 237)

Dr. David Lorge Parnas

Dr. Jan Madey

Software Engineering Research Group
CRL, McMaster University,
Hamilton, Ontario, Canada L8S 4K1

This paper explains how we can produce documentation for computer systems that is analogous to the precise and detailed documentation produced in other areas of engineering. It shows how essential properties of computer systems, and their components, can be described by a set of mathematical relations. We can deal with real-time characteristics of these systems by allowing time-functions (functions whose domain is a set of values intended to represent time) to be used in the domain and range of the relations. Our approach is intended to support the systematic production of design documents and to permit thorough review and validation.

The production of design documents plays a key role in engineering practice. The validation of documented designs, using pre-established criteria, is a major part of engineering. Conventional engineering documents are sufficiently detailed and precise that one can, for example, derive differential equations from the information that the contain. We propose similarly precise documents for computer systems and their components.

This paper discusses the content of certain computer systems documents, without specifying their from. To accomplish this it defines documents in terms of the mathematical functions that must be described. Representational issues are discussed in separate papers.

The documents described in this paper include: the "system requirements document", the "system design document", the "software requirements document", and optional "software behaviour specification", the "module interface specification", and the "module internal design document". The content of each of these documents is specified precisely. Some other documents, including hardware descriptions and communication protocol descriptions, are mentioned briefly.