Several times, I have been involved in starting a project/feature and realising that there exist issues that are yet to be discussed, either with external teams, other departments, or the relations team of a third-party provider. This has made me spend more time than necessary building. In search of a solution to ensure such tragedies do not befall me again or the occurrence is reduced, I came in contact with Software Design Document (SDD). This is a document that ensures that you ask all the necessary questions needed, clear all doubts you have, and get reasonable feedback before you proceed to write a single line of production code.

This article discusses what an SDD is, why some engineers do not want it and while other engineers embrace it, tips on writing an SDD, some necessary components of a design doc, and how to measure if the documentation process was a waste of time.

What is a Software Design Document?

An SDD provides a detailed description of your software design. It functions as a reference for software engineers to build. It contains assumptions, dependencies relating to the software and its uses, general constraints, goals, guidelines, and all development methods involved in developing the software.

Arguments against SDD

• Humans not wanting to write: Writing documents can be tiresome. Some engineers have formed the habit of documenting after building since building is where the fun is. Sometimes you are staring at the screen not knowing where to start or how to continue.
• Pace of software growth: This is similar to the argument that people have against writing comments, it is argued that the code is likely to move and change so fast that the comment becomes obsolete since the engineer might not remember to update it. Now compare this to a doc separate from your code. The likelihood of keeping up might be lower. Assuming this becomes true, then the developers who built a whole multi-page document might feel like they had wasted time putting it all together and the developers who are new to the system might not be able to trust what the SDD says again.
• Management pressure: Others complain that the pressure from management reduces the chances of dedicating time to putting together a whole document.

Arguments for SDD

• Timeline Calculation: Knowing exactly what to do and how you plan to do it, makes it easier to calculate how long it will take for it to be done with ease and better accuracy.
• Meet Stakeholders Criteria: It becomes easier to know exactly what the stakeholders are looking out for since you think about the task thoroughly before building, asking questions for clarity, sharing the documents with all stakeholders, and getting feedback. This makes it easier to build systems that meet the stakeholder's criteria.
• Point of Reference: The document serves as a point of reference whenever you are unsure how to proceed or have others mentioning new issues with claims that it was discussed before you started building the project.
• Easier to onboard new Engineers to the Project: The document ensures that any engineer joining the team can easily pick up the project since the SDD is easy to read and comprehend and covers all aspects of the project.
• Decision making: It ensures that all design decisions are made and the ones not made are noted.

Tips for Writing an SDD

• Keep it simple: Make it so simple that even a five-year-old reading the doc will have no other option than to understand what you have written. Okay, that may be over the top, but you get the point.
• Use of Images: Where necessary, throw in something pictorial to drive home the point. It might be a chart, diagram, or graph. Also, provide a link to the editable copy.
• Jokes: Just like salt to a meal, ensures that the meal does not taste bland. Adding safe-for-work jokes to your doc will spice it up a little and make it not a boring read. But like salt to a meal, adding too much might distract from the purpose.
• Preempt: Preempting possible scenarios, and questions your reviewers may throw at you will help you go through it and get fully prepared before presenting it to your reviewer.

Deciding if the SDD is a Success

It is either you finish the task on time, with it meeting stakeholders' requirements and running properly, or you find an issue that needs solving before you complete the project. You then look to ensure it is not a dead end and if it is a dead end, you may decide to leave the project or find a better solution.

Components of a Design Doc

• Title and People: This section contains the document’s title, authors, reviewers, the date the document was last updated, and everyone who will work on the project alongside you.
• Summary: This section contains an easy-to-grasp top-level summary every engineer should read to decide if they are meant to go on reading the document.
• Background: In this section, we discuss what the problem we are trying to solve is, why a solution is necessary, how the solution can be accessed, and how the solution fits into the goals and strategy of the team.
• Goals: This section looks at how success will be measured and the tools to measure it. It also looks at how it affects the end user, especially in scenarios where you have direct access to them. Either the direct users are humans or other systems.
• Milestones: Your document should contain a clear high-level list of important activities when they are expected to be accomplished, and who is responsible for accomplishing them.
• Solutions: Here, we look into the existing solutions (if any) and how the solution is being used. Then we look into the new solutions, the technical diagrams, architecture, and system designs as well as the user stories to explain them all.
• Discussion: All unanswered questions are presented so that the reader can weigh in their opinions (if any).

Conclusion

I believe having a doc like this will solve the problems I faced, mentioned at the beginning. I have started using one for my team and me. Though it does not include all the components mentioned since they are small tasks expected to run in a sprint or two. But having a document similar to this has been of immense blessing in helping us solve a lot of issues before building. If you are not in favour of the SDD, it is understandable. We all will not like everything ☺️.

If you made it this far, thanks for reading!