Dec 06, 2018

How to Write a Technical Specification or Software Design Document (SDD)

blog_sdd

If you are a developer, reading and writing software design documents — also known as technical specification documents — is part of your routine.

It is also the part that everyone loves to hate, so before diving deeper into what makes a software design document great, it's important to remind ourselves why we need to write it in the first place and what impact it may have on the ultimate success of your project.

Why write a software design document?

While it may be tempting to dive into coding early on, it's almost always a bad idea.

People often discount the importance of having a design document thinking that its main point is to teach others about your system or serve as documentation later on. While those are among the useful side effects, they are not the reason why we write design docs.

The real goal of writing a software design document is to force you to really think through the design and gather feedback from your team, allowing you to thoroughly evaluate your project before you waste a bunch of time implementing the wrong solution or the solution to the wrong problem.

A detailed and thorough design document remains the most useful tool for making sure the right work gets done. As a rule of thumb, if you are working on a project that might take over a month of your time, you should probably write a design doc.

The anatomy of a software design document

A software design document describes the solution to a problem. So naturally, since every problem is different, there can be no one-fits-all template. While your project may require a custom design document structure, you might want to consider including some of the following commonly used sections:

  • Title and people

    The title of your design document and the list of people planning to work on the project.

  • Overview

    A high-level summary that every engineer at the company should be able to understand.

  • Context

    An explanation of why this project is necessary and how it fits into the overall strategy.

  • Goals (and non-goals)

    A description of the expected impact and the metrics that will be used to measure success.

  • Milestones

    A breakdown of the project into a list of measurable and timed checkpoints.

  • Current solution

    A description of the current implementation, e.g. with a user story.

  • Proposed solution

    A specific, detailed proposal for a new technical architecture.

  • Alternative solutions

    The pros and cons of the alternatives, e.g. 3rd-party or open source solutions.

  • Discussion

    Any open issues that you need input on or aren’t sure about.

  • Scope and timeline

    The breakdown of how and when you plan on executing each part of the project.

Here's what a software design document could look like in Nuclino:

software-design-document-sdd

Tips for writing a great SDD

The style of writing a software design document is purely subjective and usually a matter of personal preference. However, a design document would only be useful if it's actively read and updated, and while this usually isn't the most exciting thing to read, there are a few ways to make the experience more engaging.

Don't write it in Word

Software development is a collaborative process, and feedback loops and reviews are crucial for a successful outcome. Word is a great tool that has its applications but it's also rigid and closed in nature. Writing a design document in Word would virtually guarantee that no one will read and let alone update it.

An ideal tool for writing an SDD is open and collaborative — Nuclino aims to be such a tool.

Keep it simple

When you are writing a software design document, your goal is not to impress some journal reviewer, it is to clearly and accurately describe your solution to your team. The best way to achieve that is to keep your language plain and illustrative. Use simple words, short sentences, bullet lists, and helpful examples wherever you can.

Make it visual with charts and diagrams

In many cases, visual aids, such as charts and diagrams, can be more helpful in conveying your point than text. In Nuclino, you can embed live diagrams by simply pasting a shared link from draw.io, Gliffy, or Lucidchart.

Do the "vacation test"

To make sure the feedback you get from your team is actually useful, make your software design document as clear as possible. Do what they call a "vacation test": if you take off on an impromptu vacation, would your team be able to read the design document and implement your solution as you intended?

Do the "skeptic test"

Before you send your design document to a reviewer, try to take a step back and think about the possible questions and doubts you might have about this design. If you identify the potential weak spots or inconsistencies you might be able to address them preemptively.

Maximizing the ROI of your design document

Before you get down to writing, here are a few final tips to help you make the most of your time and efforts.

Get everyone involved

Everyone working on the project needs to be involved in the process from the start. Keep it collaborative. It may lead to a lot of discussions early on, but it will save you time getting everyone on the same page later.

Gather feedback early

Before you invest any time in writing and get attached to any specific solution, ask an experienced engineer who is familiar with the edge cases of the problem to be your reviewer. Get his feedback and keep him in the loop throughout the project.

Don't be afraid to prototype

Do not start writing production code for the project before writing the design document, but feel free to prototype potential solutions to validate your idea. Write only exploratory code, make it a rule that none of it gets merged into master.

Address all points of contention

Reserve the "Discussion" section of your software design document to address the feedback you get from your team. Don't leave comments hanging — commit to addressing all questions and comments within a day.

Treat the SDD as a living document

Ideally, your design document evolves as you implement the design. To keep all the stakeholders on the same page, you would want to update the document every time you make changes to the original solution or update the scope or timeline of your project. To draw the attention of the stakeholders to a particular update in Nuclino, simply @-mention them and they will get an instant notification.

How to evaluate the success of your design doc?

Whether the design document was worth the time and effort you invested in writing it is not judged by whether the project gets successfully implemented. In fact, the primary goal of writing an SDD is to weed out projects that are not practical or viable.

Writing the design doc forces you to think through different parts of the technical architecture of your solution. Feedback from your team helps you identify the riskiest part of it. If it turns out to be impossible to implement, you only spent a few days on the process instead of wasting potentially months only to abort this project later.

The point of a design document is to ensure you only spend your time on the right things, and if it results in you abandoning a flawed concept early, it was worth the time you invested writing it.