Co-Founder Taliferro
Introduction
The following is an attempt to put together a complete yet reasonably flexible set of guidelines for a software design specification. Wherever possible, I have provided guidelines (instead of prescribing requirements) for the contents of various sections and subsections. Some may prefer to require more detailed subsections of a particular area, choosing one or more of the subsection topics from the list of guidelines provided. This post is a template for a template. I have reviewed information from many sources:
- Software Engineering (Pressman, Sommerville, and Van Vliet), Object-Oriented Development (Booch, Rumbaugh, Berard, Wirfs-Brock)
- DoD-Std
- various SEI reports
- Mil-Std documentation requirements (2167/2167A)
- IEEE-830 for software requirements
- IEEE documentation standards (particularly IEEE-1016 for software designs
I tried avoiding assuming or imposing a particular software development methodology or paradigm and emphasizing content more than format. My desire would be that a completed software design specification meet the following criteria:
- The guide should help in conveying enough information and understanding about a project implementation. It should be able to serve as training material for new project members adequately. The reader can understand what is being said in design meetings and will feel free when they are first asked to create or modify source code.
- It should serve as "objective evidence" that the designers and implementers are following through on their commitment to implement the functionality described in the requirements specification.
- It needs to be as detailed as possible while at the same time not imposing too much of a burden on the designers and implementers that it becomes overly difficult to create or maintain.
Please note that there are no sections in this post describing administrative or business duties or proposing plans or schedules for testing or development. The areas in this post are concerned solely with the design of the software. While there are places in this post where it is appropriate to discuss the effects of such plans on the software design, most of the details concerning such procedures belong in one or more separate documents.
System Overview
Provide a general description of the software system, including its functionality and matters related to the overall strategy and its design (perhaps including a discussion of the basic design approach or organization). Feel free to split this up into subsections (and subsubsections, etc ...).
Design Considerations
Describe any issues that need to be addressed or resolved before attempting to devise a complete design solution.
Assumptions and Dependencies
Describe any assumptions or dependencies regarding the software and its use. These may concern such issues as:
- Related software or hardware
- Operating systems
- End-user characteristics
- Possible and probable changes in functionality
General Constraints
Describe any global limitations or constraints that significantly impact the design of the system's software (and describe the associated implications). Such conditions may be imposed by any of the following (the list is not exhaustive):
- Hardware or software environment
- End-user environment
- Availability or volatility of resources
- Standards compliance
- Interoperability requirements
- Interface/protocol requirements
- Data repository and distribution requirements
- Security requirements (or other such regulations)
- Memory and other capacity limitations
- Performance requirements
- Network communications
- Verification and validation requirements (testing)
- Other means of addressing quality goals
- Other requirements described in the requirements specification
Goals
Describe any goals, guidelines, principles, or priorities which dominate or embody the design of the system's software. Such goals might be:
- The KISS principle ("Keep it simple stupid!")
- Emphasis on speed versus memory use
- working, looking, or "feeling" like an existing product
For each such goal or guideline, unless it is implicitly obvious, describe the reason for its desirability. Feel free to state and explain each plan in its subsubsection if you wish.
Development Methods
Briefly describe the method or approach used for the software design. Provide a brief explanation of why all or part of it was used or not used. If several methods were seriously considered, each such practice should be mentioned. If one or more formal/published methods were adopted or adapted, include a reference to a more detailed description of these methods.
Architectural Strategies
Describe any design decisions and strategies that affect the overall organization of the system and its higher-level structures. These strategies should provide insight into the fundamental abstractions and mechanisms used in the system architecture. Describe the reasoning employed for each decision and procedure (possibly referring to previously stated design goals and principles) and how any design goals or priorities were balanced or traded off. Such choices might concern (but are not limited to) things like the following:
- Use a particular product type (programming language, database, library, etc. ...)
- Reuse of existing software components to implement various parts/features of the system
- plans for extending or enhancing the software
- User interface paradigms (or system input and output models)
- Hardware and software interface paradigms
- Error detection and recovery
- Memory management policies
- External databases and data storage management and persistence
- Distributed data or control over a network
- Generalized approaches to control
- Concurrency and synchronization
- Communication mechanisms
- Management of other resources
Each effective strategy employed should be discussed in its subsection or (if it is complex enough) in a separate design document (with an appropriate reference here). When describing a design decision, make sure that you also discuss any other significant alternatives that were considered and your reasons for rejecting them (as well as your reasons for accepting the choice you finally chose). Sometimes it may be most effective to employ the "pattern format" for describing a strategy.
System Architecture
This section should provide a high-level overview of how the functionality and responsibilities of the system were partitioned and then assigned to subsystems or components. Please don't go into too much detail about the individual members themselves (there is a subsequent section for detailed component descriptions). The primary purpose here is to understand how and why the system was decomposed, and how the individual parts work together to provide the desired functionality.
At the top-most level, describe the software's major responsibilities and the various roles that the system (or portions of the system) must play. Please explain how the system was broken down into components/subsystems (identifying each top-level component/subsystem and the roles/responsibilities assigned to it). Describe how the higher-level components collaborate to achieve the required results. Remember to provide some rationale for choosing this system decomposition (perhaps discussing other proposed decays and why they were rejected). Feel free to use design patterns, either in describing parts of the architecture (in pattern format) or referring to elements of the architecture that employ them.
Suppose there are diagrams, models, flowcharts, documented scenarios, or use cases of the system behavior and structure. In that case, they may be included here (unless you feel they are complex enough to merit being placed in the Detailed System Design section). Diagrams that describe a particular component or subsystem should be included within the specific subsection that describes that component or subsystem.
Note: This section (and its subsections) applies only to the system's newly developed (or yet-to-be-developed) portions. Suppose parts of the system already existed before this development effort began. In that case, you only need to describe the pre-existing features that the new parts of the system depend upon and only in enough detail to describe the relationships and interactions between the old and new parts. Pre-existing parts that are modified or enhanced need to be related only to the extent necessary for the reader to understand the nature of the changes that were made.
Subsystem Architecture
If a particular component merits a more detailed discussion than what was presented in the System Architecture section, provide that more detailed discussion in a subsection of the System Architecture section (or it may even be more appropriate to describe the component in its design document). If necessary, describe how the component was further divided into subcomponents and the relationships and interactions between the subcomponents (similar to what was done for top-level components in the System Architecture section).
If any subcomponents are also deemed to further merit discussion, then describe them in a separate subsection of this section (and in a similar fashion). Proceed to go into as many levels/subsections of discussion as needed for the reader to gain a high-level understanding of the entire system or subsystem (but remember to leave the gory details for the Detailed System Design section).
Suppose this component is substantial and complex. In that case, consider documenting its design in a separate document and simply including a reference to it in this section. If this is the option you choose, the design document for this component should have an organizational format that is very similar (if not identical to) this post.
Policies and Tactics
Describe design policies and tactics that do not have sweeping architectural implications. This means the guidelines would not significantly affect the overall organization of the system and its high-level structures), but affect the interface details and implementation of various aspects of the system. Such decisions might concern (but are not limited to) things like the following:
- Choice of which specific product to use (compiler, interpreter, database, library, etc. ...)
- Engineering trade-offs
- Coding guidelines and conventions
- The protocol of one or more subsystems, modules, or subroutines
- The choice of a particular algorithm or programming idiom (or design pattern) to implement portions of the system's functionality
- Plans for ensuring requirements traceability
- Plans for testing the software
- Plans for maintaining the software
- Interfaces for end-users, software, hardware, and communications
- Hierarchical organization of the source code into its physical components (files and directories).
- How to build and generate the system's deliverables (how to compile, link, load, etc. ...)
Each particular policy or set of tactics employed should probably be discussed in its own subsection or (if it is large or complex enough) in a separate design document (with an appropriate reference here, of course). When describing a design decision, make sure that you also discuss any other significant alternatives that were considered and your reasons for rejecting them (as well as your reasons for accepting the choice you finally chose). For this reason, it may be convenient to use one of the more popular "pattern formats" to describe a given tactic.
For this particular section, it may become difficult to decide whether a particular policy or set of tactics should be discussed in this section, in the System Architecture section, or the Detailed System Design section for the appropriate component. You will have to use your "best" judgment to decide this. There will usually be some global policies and tactics that should be discussed here. Still, decisions about interfaces, algorithms, and/or data structures might be more appropriately discussed in the same (sub)section as its corresponding software component in one of these other sections.
Detailed System Design
Most components described in the System Architecture section require a more detailed discussion. Other lower-level components and subcomponents may need to be described as well. Each subsection of this section will refer to or contain a detailed description of a system software component. The discussion provided should cover the following software component attributes:
Classification
The kind of component, such as a subsystem, module, class, package, function, file, etc.
Definition
The specific purpose and semantic meaning of the component. This should refer back to the requirements specification.
Responsibilities
The primary responsibilities and behavior of this component. What does this component accomplish? What roles does it play? What kinds of services does it provide to its clients? For some features, this may need to refer back to the requirements specification.
Constraints
Any relevant assumptions, limitations, or constraints for this component. This should include restrictions on timing, storage, or component state and might consist of rules for interacting with this component (encompassing preconditions, postconditions, invariants, other constraints on input or output values and local or global values, data formats and data access, synchronization, exceptions, etc.)
Composition
A description of the use and meaning of the subcomponents that are a part of this component.
Uses/Interactions
A description of these components' collaborations with other features. What other components is this entity used? What further details does this entity use (including any side-effects this entity might have on different parts of the system)? This concerns the method of interaction as well as the exchange itself. Object-oriented designs should describe any known or anticipated subclasses, superclasses, and metaclasses.
Resources
A description of any managed, affected, or needed resources by this entity. This should include discussing possible race conditions and deadlock situations and how they might be resolved. Resources such as memory, processors, printers, databases, or a software library are external to the design.
Processing
A description of precisely how this component performs the duties necessary to fulfill its responsibilities. This should encompass a description of any algorithms used; changes of state; appropriate time or space complexity; concurrency; methods of creation, initialization, and cleanup; and handling of exceptional conditions.
Interface/Exports
The set of services (resources, data, types, constants, subroutines, and exceptions) that are provided by this component. The precise definition or declaration of each such element should be present, along with comments or annotations describing the meanings of values, parameters, etc. .... For each service element described, include (or provide a reference) in its discussion a description of its important software component attributes (Classification, Definition, Responsibilities, Constraints, Composition, Uses, Resources, Processing, and Interface).
Much of the information in this section is not necessarily expected to be kept separate from the source code. Much of the information can be gleaned from the source (especially if it is adequately commented). This section should not copy or reproduce information that can be easily obtained from reading the source code (this would be an unwanted and unnecessary duplication of effort and would be very difficult to keep up-to-date). It is recommended that most of this information be contained in the source (with appropriate comments for each component, subsystem, module, and subroutine). Hence, it is expected that this section will primarily consist of references to or excerpts of annotated diagrams and source code. Any referenced charts or source code excerpts should be provided in any design reviews.
Detailed Subsystem Design
Provide a detailed description of this software component (or a reference to such a description). Complex diagrams showing the details of component structure, behavior, or information/control flow may be included in the subsection devoted to that particular component (although, unless they are very large or complex, some of these diagrams might be more appropriately included in the System Architecture section. The description should cover any applicable software component attributes (some of which may be adequately described solely by a source code declaration or excerpt).
Glossary
An ordered list of defined terms and concepts used throughout the document.
Tyrone Showers