How to Write a Software Design Document

By Alissa Crowe-Scott

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.

Step 1

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.

Step 2

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 - Assumptions - Constraints - 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 - Security measures - Performance - Reliability

Step 3

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.

Step 4

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.

Step 5

Include enough detail for the programmers, while incorporating some high-level summaries for the managers.

Step 6

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.