How to write a software design document

Written by alissa crowe-scott
  • Share
  • Tweet
  • Share
  • Pin
  • Email
How to write a software design document
Sharpen your pencils and get ready to design! (technical elements image by pdtnc from

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:


  1. 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.

  2. 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

  3. 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.

  4. 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.

  5. 5

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

  6. 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.

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.

Don't Miss

  • All types
  • Articles
  • Slideshows
  • Videos
  • Most relevant
  • Most popular
  • Most recent

No articles available

No slideshows available

No videos available

By using the site, you consent to the use of cookies. For more information, please see our Cookie policy.