As a software engineer, you need to spend a lot of time reading and then writing a design document. There is a strong correlation between good design docs and the ultimate success of a project. To write a good design document, you need to understand the following first:
Why should you write in a design document?
What should you include in the design document?
What are the best practices for writing the design document?
What is the process you need to follow?
No 1: Why should you write in a design document?
A design doc is also known as a technical spec. It is a detailed description of how you are going to solve a problem. It is essential for you first to create a design doc before diving into the coding. A design doc is the most important and useful tool that you have to make sure that the work is well done.
The ultimate goal of a design doc is to help you to work efficiently by forcing you to think through the design as well as gather information from others. Many people get confused because they feel that the purpose of the design doc is to maintain documentation for the project. There are others who think it is mainly created to help others learn about the system. These are, in fact, some of the beneficial side effects but not the main idea behind creating them.
As a general rule, you need to create a design doc when you are working on a project that requires at least one engineer per month. But it does not mean smaller projects will not benefit from using a design doc.
No 2: What should you include in the design document?
In a nutshell, a design doc describes in detail the solution that you are giving to a problem. The nature of each problem is different than the others. You need to structure the design doc differently. To begin with, these are the things that you can include in the design doc.
Title and People
You should include the title of the design doc and also include the names of the authors who are planning to work on the project. Also, add the reviewers of the document and the date you prepared it.
Overview
It is essential for you to include a high-level summary at the start of the doc so that every engineer in the company can read and understand it. Ensure that the summary is at least three paragraphs long.
Context, Goals, and Non-Goals
Add the context of the problem that is at hand and the reason why this project is necessary. Include information that is essential for people to assess the problem thoroughly.
In the goals section, includes metrics that you will use to measure the success.
Take time to describe in detail the user-driven impact on your project. Also, include non-goals to indicate which problem you will not fix so that others understand the scope of the project.
Milestones
It is essential for you also to include milestones so that your PM and your manager’s manager can skim through the doc to see when you are going to complete certain parts of the project. It is wise to use calendar dates so that it becomes easy for people to check on those dates to see if you achieved your milestones.
Other Information You May Need to Include
It is good to include additional sections in the doc like the current, alternate and proposed solutions. Monitoring, alerting, cross-team impact, discussion as well as detailed scoping and timelines are some categories that you should consider adding.
No 3: How to Write the Design Doc
You should follow the right steps if you are planning to write the design doc. Keep your English as simple as possible so that anyone who gets the document does not find it hard to read through it. Keep the sentences short and use bulleted or numbered lists.
It is a good idea to include a lot of diagrams and charts. But you need to ensure that the diagram or chart is an editable version. Also, include real numbers like the number of database rows and number of user errors, etc.
Try to make your design doc interesting by including some fun elements. Never overdo anything as it might turn people off, but making an engaging document is a good idea. Once it is ready, you need to evaluate it to see if there can be any improvements you can make on the doc. By doing this, you will also know if someone can handle it if you are away from the office.
What is the Process You Need to Follow?
It’s best to include all those who are working on the process and to ensure that they are there in the design phase. Getting ideas from everyone is essential. Secondly, it is necessary for you to prototype potential solutions.
Validate the solutions that you are planning by sharing the information with a senior engineer whom you have as a reviewer to see if he gets convinced with the set of solutions that you have for the problem. Once you and your reviewer feel you’re ready to sign off on it, you can treat this design doc as a living document. It is time to implement the design. Update the document whenever you make any changes.
These are the things you should follow when creating a good software design doc for a successful project.
