The typical benefits of a software design document
include:
The designs of the individual packages and modules (e.g.,
classes, class methods, procedures) within one or more
software components are localized so that they can be
properly evaluated and maintained.
Well documented code is more easy to reuse.
Additions to the development team can be transitioned in
more smoothly because they can get up to speed with standard
documentation and not rely on word of mouth.
It captures important design decisions such as
responsibilities that drive the implementation.
Software Development Team, which use the software
design document to drive the implementation, unit
testing, and package integration testing of the
software.
The contents above have been written under the assumption
of an object-oriented design approach which implies that
units are classes. The unit design documentation should be
modified to that used to describe class methods if a
procedural language is to be used.
An endeavor can produce:
A single software design document covering all software
packages of all software components.
Multiple software design documents:
One software design document for each software
component.
One software design document for each software
package.
No software design document (e.g. if the designs of the
individual software units are captured in some other form
such as
Javadoc).
Software design documents should be living documents that
evolve as the software design is iteratively and
incrementally produced and maintained.
Due to the incremental and iterative nature of modern
software development cycles, it can be extremely difficult,
time-consuming, and expensive to ensure that the software
design documents remain consistent with the resulting source
code implementations without use of an integrated development
environment (IDE) that supports forward and reverse
engineering between the design and the code.
Much of the contents of the software design document can
(and should) be stored in the form of comments in the
relevant package and unit source code. If a parallel
development cycle is used in which software design and
programming occur concurrently and if programming standards
require the documentation of much of the design in the form
of comments, then much of the textual information in the
software design document can be safely removed because it is
redundant. In this case, the software design document
primarily contains diagrams and more summary
information.
The design of user-interface modules can be stored in the
human-interface design document and included in the
software design document by reference.
Manually or automatically generated paper
document.
Electronic document
A logical collection of its contents stored by an
upperCASE tool.
The organization (content and format) of the software
design document(s) should mirror the structure of the
associated software components. The quality of the
document(s) will be improved to the extent that the
components are partitioned into cohesive, loosely-coupled,
modular packages and classes that exhibit proper
encapsulation and information hiding.
On small software-only endeavors, the software design
document and the
system architecture document may be combined into a single
document.
