How I Wrote My First Software Design Doc To Win New Project
Published on • 4 minutes readOne day, inspired by how Google approaches documentation, I decided to write my first Design Doc.
I was figuring out a new project for the R&D team that would allow us to apply the research we did. It was a perfect moment to apply the knowledge from the “Software Engineering at Google” book I recently read.
The topic I was researching was quite complex because it was a mobile app using a custom blockchain. I knew that convincing multiple stakeholders and explaining everything each time, wouldn’t simply work.
That’s when I started filling out the Software Design Doc template.
Writing Project Abstract #
The main point of it was an Abstract. It explains what the app is, what would be its purpose, and finally what results we want to achieve from the research.
I also had to explain a few concepts around blockchain, so it’s clear to everyone who would be working on such a project in the future.
Adding Goals and Non-Goals to Software Design Doc #
Explanation allowed me to gather the list of goals for the project, but something which was even more important was the list of non-goals.
It was a fun app to use for a closed circle of people. We were never supposed to release that to the public. The goal was for the developers to learn to build this type of app.
Going forward - we were never supposed to create an app that would use a real blockchain network and use cryptocurrency such as Ethereum.
It was a really important part of the Design Doc, and I believe that it was something that helped me to get the buy-in and make this project happen.
What is the Main Design Doc Purpose? #
At this point, you might think that Design Doc made its purpose, and it will be no longer needed if stakeholders agreed to build it.
That’s wrong. It was a living document, which we started to update.
The first thing we did, was to agree upon an architecture for the app. As a team this time, we described how the app should be built and listed the main dependencies to use.
It became crucial in a fast pace, rotation-prone environment like R&D. It allowed to speed up the onboarding process, which could be done partially async.
It will always be a tool included in my developer onboarding documentation.
How Does Software Design Doc Help Validate Assumptions? #
Design Doc is also called a Request For Comments in different companies. In my case, it exactly turned out to work this way.
The architecture we outlined initially wasn’t created properly, and that was fine because the app's purpose was to find out what does work and what doesn't.
Design Doc allowed us to communicate our plans, and receive feedback. It turned out that some assumptions were wrong and we wouldn’t have the resources to build it this way.
Software Design Doc Used by Another Team #
The best thing that happened to my Design Doc, and to prove how useful it is, was a moment when the project split. Another team kicked off their version of my idea to also learn about Blockchain.
The main resource they followed when designing their solution, was the design document I wrote.
Who Was The Main Recipient of My Documentation? #
Although the document was created with stakeholders in mind, it was the most useful for project team members.
It was mobile app-specific, but it proved useful for backend devs, web frontend devs, and the DevOps team too.
The most interested teams were UX and UI teams, which had to understand all the complicated things we were doing with the app. It was a challenge to design an app that handles security in a different way than usual and where backend requests are taking some time to pass through.
How to Get The Most of Software Design Doc? #
Maintenenace process #
One thing which is worth doing is proper maintenance of the document. I didn’t think that it will be so useful for the team’s reference and onboarding.
Stakeholders and Approvers #
It’s worth including the stakeholders and approvers of the document, but it’s important to update this list often. In my case, it was confusing for the team, to whom to reach out with questions.
Resources #
The list of resources and designs was useful to everyone It's important to remember that this list changes often and should include the new files created by the team.
Specification #
I wasn’t convinced to create a screen-by-screen specification with explanations. There was a Design link available, so what’s the point? In retrospect, I would at least describe the basic flow, which would speed up onboarding.
Summary #
When I was creating my first Design Doc, the main assumption was to learn to do it and check if it will work. To my surprise, my little experiment became a key document for stakeholders and team members.
The Design Document in the form of a request for comments is and will be one of the most important tools for a Tech Lead.
What is Your Experience with Software Design Docs? #
Let me know your thoughts on Threads - @this.dev or Twitter - @IdaszakDaniel.
Tweet