How to Write a Good Software Design Doc

Publication Date: 20 Apr 2019
Author: Kelly Higgins

Dear Community, in this post, you will become acquainted with defined aspects of a design document. In general, this article consists of the following:

1. Destination of the design document

2. Structure of the technical specifications

3. How to write the design doc correctly

4. The process

Destination of the Design Document

Frequently, people think that the design document, also known as technical specifications, is created to bring awareness of define system to a target audience. This is the correct opinion. But, it reflects the beneficial moment. The principal role of the design doc is building a reliable basis for the project, discussing the issue with professionals.

Structure of the Technical Specifications

Title and People

Here, you write the title of the document and a list of people who take part in a project (author, reviewer). As well, the date of the last changes or additions to the specifications should be included.

Overview

This is an exact summary of the project. Its volume shouldn’t be more than 3 paragraphs. Try to comprise only the most essential information that shows the main issue clearly. Engineers in a company consider this section and then make a decision if it’s reasonable to continue reading the following parts of the doc.

Context

Overall description of the problem that is expected to be solved by the launch of the project. Also, you should direct what knowledge people need to have to understand the matter.

Goals and Non-Goals

Goals part shows the project’s impact on a user, as well as information on how to evaluate the successful implementation via metrics should be included. Non-goals section is also significant. Here, identify the points that you will not fix.

Milestones

The project should be accompanied by a schedule. This aspect is a route that shows when defined part of the project is planned to be implemented.

Current Solution

Describe features of interrelation between users and the system. It is an appropriate decision to submit examples that clearly reflects the current state of the affairs.

New Solution

This is the core section of your design doc. You should bring the information in the most understandable way. At first, describe the solution generally. Then provide detailed analysis, including use cases, diagrams, etc. Bring the solution gradually to enable implementing without delays and other problems. Engineers need to get well structured technical specifications to perform their work instructively.

Optional Solutions

If you have alternative ideas to the main solution, it will be reasonable to submit them, demonstrating the pros and cons. Besides, you can provide a comparison with solutions from the open source.

Cross-Team Impact

Apart from the description of the major principles of the project, also, form the list of the secondary points, assessing their impact on particular significant moments. For instance, calculate the costs related to the implementation and its support. Further, note the possibility of a regression in the system. Take into account an impact on security vulnerabilities. And, of course, provide the ways that enable customer support team to bring this information to the target audience.

Open Questions

When devising new solutions, you may face difficulties on the way of making a precise conclusion. As the project is introduced to the individuals, who are aware of the professional specifics, it will be useful to share the contentious parts with them.

How to Write the Design Doc Correctly

As it may seem, writing of the technical specifications is similar to the academic style. But, such a view is misleading. Your doc should be written in a simple manner to be easy for perception by the colleagues and other individuals, who participate in the assessment. Don’t use complicated sentences. Try to include bullet lists and situations that demonstrates the solution step-by-step. Also, don’t forget about the charts and diagrams. These ways of transferring the information are more comprehensible in comparison with a text.

When your writing is completed, try to read it as you are the person who will assess the project. Such an approach is practiced to find out vulnerabilities of the work. And, indeed, think over possible questions that may arise when the colleagues get acquainted with the information.

The Process

The writing of the design doc is accompanied by particular stages. When ideas have a place, you should discuss them with experienced engineers. Turn to the persons, who have a deep awareness of the issue. Demonstrate them the project’s features on the whiteboard and get an approval for the further work. When the ideas are structured in the written form of the design doc, submit the document to the reviewer again and add his name to the corresponding section “Title and People”. This action had to be confirmed by stamp. After this stage, you have to share the specifications with other colleagues.

Try to discuss the work with different people in person. Adhering such way, you get the evaluation of the issue from various perspectives. This creates a strong ground for a comprehensive explanation of the project’s points and its quality in general.