A software design document is the “how to” of software life-cycle documentation. It details how the software requirements should be implemented and it gives the programmers a blueprint to follow.
The software design document is a written contract between you, your team, your project manager and your client. When you document your assumptions, decisions and risks, it gives the team members and stakeholders an opportunity to agree or to ask for clarifications and modifications. Once the software design document is approved by the appropriate parties, it becomes a baseline for limiting changes in the scope of the project.
- Skill level:
Investigate the document formatting/template used in the software requirements document. This includes title page, page numbering format, section numbers and revision history. Use the same or similar document format for the software design document.
Incorporate some, if not all, of the following elements:
High level summary
Definitions of any non-standard symbols, shapes, acronyms, and unique terms in the document
How each requirement will be achieved
Software risk analysis
Development procedures and coding guidelines
Standard languages and tools
Definitions of variables and a description of where they are used
Logical structure and logical processing steps
Error, alarm and warning messages
Consider how to structure the design document. This is especially important when you’re designing a large, complex system. Break the system into logical parts and use these parts as the section headers in the software design document. If the system is really large, create multiple design documents, each one dealing with a particular part of the system.
Give each design element a unique identifier. This will allow it to be traced back to the applicable requirement and eventually to the applicable testing.
Include enough detail for the programmers, while incorporating some high-level summaries for the managers.
Develop prototypes. If you can include some screen shots or sample code in the design document, this will help to convey your design intent. Developing prototypes should also decrease the time that will be spent coding.
Tips and warnings
- Keep in mind that this design document will most likely be used for maintaining the system long after you’re done programming it. Add items that may be helpful in troubleshooting.
- Be sure to be consistent with terminology throughout the document, and between the design document and the requirements document.
- According to Steve McConnell in the Software Project Survival Guide, “The amount of design work and the formality of that work depend on two factors: the expertise of the project’s developers and the difficulty of the project.” If the project has expert programmers and is a simple project, the design can be less detailed. But if the project has inexperienced programmers, uses unfamiliar or untested technology or demands high reliability, then a more detailed design approach may be warranted.
- 20 of the funniest online reviews ever
- 14 Biggest lies people tell in online dating sites
- Hilarious things Google thinks you're trying to search for