A software design document is written to meet the following key objectives:
- Submit to the client for a review and sign off before proceeding to the next stage of project life cycle
- Facilitate development of efficient code by system developers
- Obtain review feedback from other designers and project managers
- Meet documentation requirements of the project
- Improve the accuracy of schedule and effort estimates for project completion
- Identify constraints during solution implementation
Contents of the document
Below is a recommended structure for a design document with guidelines on what each of the sections should contain.
Introduction: This section should contain a brief description of the project background and include the design goals.
Architecture: This section should cover the Business Architecture and the Technical Architecture. The former would include the different functional modules, key functionalities that are a part of each module and the business components in each module. The Technical Architecture should contain details about the technology platform, interfaces, data exchange, file formats, human interaction with the system and the modules. Details pertaining to each of the above headings should be organized in separate sub sections.
The sub sections should contain details about the implementation. For example, the section on interfaces should have information pertaining to the context and purpose of each interface, what modules would use the interfaces, how the interfaces will be referenced and what information will be required for referencing.
Application Operation: All details pertaining to how the system would work post implementation should be documented here. Information should be grouped under different headings including types of users, how the system should be installed, what are the licensing terms, how future releases will be delivered and installed, procedures for installing future versions/releases and the basic troubleshooting techniques.
Development: This section should lay out the development plan and list the dependencies, resource requirements (staffing, software and hardware licenses) and the development approach.
Appendix and References: This section should be used to reference other documents. Examples of such documents are the baselined Requirements Specification Document and the Functional Specifications Document.
Checklist
It is important to include the following aspects when the design document is developed. These are not mandatory; however, paying attention to these aspects makes the design document ‘complete’.
- Version history: Including a table in the beginning of the document to record the review history of the document is a good practice. At the minimum, information pertaining to reviewer, review date and details of changes should be included here. This should be placed before the Table of Contents.
- Conformance to standards: All organizations will have enterprise standards to which the system being developed need to conform. Enterprise standards would also dictate naming conventions for documents and files; it is important to adhere to these guidelines and standards. In many instances, the acceptance of the product would be contingent on adherence to standards. Therefore, it is advisable to provide a list of standards or reference these standards. This will serve as a critical input for developers when the system is being developed.
- Issue Log: During the course of project execution, issues are flagged for resolution and some issues remain unresolved at the time of documenting the application design. Such ‘open issues’ need to be logged here.
- Traceability matrix: Requirements need to be traced all the way through the life cycle of a project for implementation. The design document should have a provision that demonstrates how the implementation of each requirement is addressed during the design stage.
Other Considerations
The design document should also include block diagrams and other pictorial representations as appropriate. A cover page and Table of Contents would impart a professional look to the document.