Writing Effective Software Design Document

Introduction

If you are a software developer or an architect, then surely you know the importance of writing effective software design documents (SDD). You can find unlimited articles on the internet related to the type of design documents, which type should have which heading, etc., so I am not going to waste your time by explaining those things again.

Now the question is this: if we already have a lot of information available on the internet, then what do we want to cover in this article and why?

I (and most likely you, as well) have come across design documents that have lots of headings, diagrams, and details, but they don't make much sense as a whole or at least do not cover all aspects that should be addressed in the document.

In this article, we will talk about the main points that we need to keep in mind while writing the design document so that it serves the intended purpose and is not confusing or misleading.

When Do We Need a Software Design Document?

Whenever there is a requirement to create/modify a feature that needs a code/architectural change in software, before starting implementation, we should have a design document that is reviewed and approved by all stakeholders involved/impacted by the change.

Design documents are an outcome of the design phase of the SDLC process. Entry criteria for a design document is a well-defined requirement document. Once the requirements get finalized in the requirement-gathering phase, the design phase starts.

Importance of Prerequisites for Audience Section

This is the most underrated part of a design document and the absence of this creates a lot of confusion for readers. Every design document should have a prerequisite section that mentions for whom this design document is intended. Let's try to understand the importance of the prerequisites for the audience section with the below example.

Let's say we have created a high-level design document (HLDD) to implement the publisher-subscriber model for inter-service communication. This has high-level details of what changes are needed in our infrastructure and which tools/frameworks are needed to implement the pub-sub model. This HLDD is intended for the architects of the infrastructure and microservices-related teams.

Now if there is no prerequisite section present and a junior developer goes through that document, there is a big chance that they will not be able to understand all the parts of SDD. This results in either the imposter syndrome because they cannot understand the document, or maybe they will post multiple unnecessary comments on the design, which would burden the writer to respond.

So to avoid such situations, it is always recommended to mention for whom you are writing the document.

Identifying the Unknowns

In an ideal scenario, an SDD starts once the requirements and impact due to dependencies (like other teams' commitments) are clear. Though this can be the case for easy levels of software modifications, for the medium and complex levels of changes, there are always a few unknowns.

It is important to mention the unknowns that should have been known at the time of SDD creation, but the details were not available. This information helps to make decisions (like effort estimates). If we know the unknowns, then it would be easier to follow up with the stakeholders to get clarification on those and modify the design document to cater to those changes.

It seems obvious to handle the unknowns, but I have seen multiple instances where the writer of SDD knew about unknowns, but those were not mentioned in the documents because the writer was following up on them offline. Over time, either the SDD writer changed the team or, in the worst case, left the company and those unknowns were not being tracked anywhere. If this happens with a complex level of SDD, then it results in a huge mess in the implementation phase of SDLC.

Dependency Analysis and Management

Dependency analysis is covered most of the time in the requirement gathering and analysis phase. In the design phase, we just need to track and follow up with stakeholders to resolve those dependencies. However, in a few cases, we find out new dependencies at the time of writing SDD, and we need to add, track, and resolve those dependencies, as well.

There are multiple opinions and ways to manage and resolve the dependencies. My opinion is that the best way is to mention all dependencies in a tabular format with columns like the table below:

​Dependency	Details	Owner	Approver	Status	Comments
Summary of dependency.	Details about the dependency.	Who is tracking/following up to resolve the dependency	The stakeholder/POC. For example, the architects of other teams who can commit to the deadlines, or can approve that changes won't affect their systems	In-progress/ approved	Details about the progress in dependency resolution

Risk Analysis

There could be points for which the assumptions would have been taken when writing the SDD. Let's say we are writing a design document to deploy the code in a distributed environment, and as the talks with the AWS sales team are in the last phase, in our design document we have considered that this architecture would be deployed on AWS.

As the deal is not yet finalized due to unforeseen reasons, a company may decide not to go with AWS and choose GCP to deploy the code. In this scenario, multiple assumptions in our SDD would go wrong and multiple changes would be needed. So the unfinalized deal with AWS is a risk for our SDD.

It is important to mention the risks and the possible impact of those in the design document so that all stakeholders are aware of them.

Definition of Done (DOD)

Every design document has a unique expectation from it, so it is impossible to tell exactly what should be the DOD of an SDD. However, in general, a design document is considered completed if the following points are addressed:

• SDD has the reference of requirement and analysis documents based on which it was created.

• Anyone who satisfies the prerequisite criteria is able to understand the SDD without putting in much effort.

• SDD covers all the points mentioned earlier in this article.

• The outcome of the design document is given in a way that sub-tasks or sub-design documents can easily be carved out using that.

• The design document has approval from all stakeholders who are either involved or going to be affected due to the changes proposed in the document.

Conclusion

There are multiple other aspects like the length of the document, number of diagrams, etc., which can help improve the quality of the document but are not covered here because it is hard to cover everything in an article. However, I have covered the essential points that we need to keep in mind to make a meaningful design document.

Happy reading!!