Well, I'm going to keep this article short and simple. Let's talk about what a design doc is and how we could write one. The explanation of what a design doc is varies from person to person but all boils down to mean one thing. I'm going to try to explain it the way I understand it, and hopefully you learn something from it
What Is A Design Doc?
Well, we could define a design document as a document a software engineer writes to explain/discuss what a project or a feature in a project is all about to other engineers on the team and for future reference/guidance and accountability, to put out their whole thought process around it, and agree on some patterns which are otherwise controversial or contentious.
Where Do you write Design Docs
Design docs could be written in any software you want to write them, but one key thing you could take into consideration is the ability of other teammates being able to leave comments on it, highlight problems they find or things that could be modified. Options you might consider would include:
Google Docs- etc.
Why Write Design Docs?
Design Docs would help you with some probems. I will try to highlight a few of them
Team Collaboration
Every member of the team gets to contribute their ideas on different pattern or ways to approach a problem. Many times when people share their view on solving problems, the problem itself gets clearer to everyone. By writing a Design Doc explaining what you're about to do, and how you intend going about doing it, you get contributions from others, which most times would lead to a better way/pattern of solving the problem. So You're basically opening up a discussion with other teammates with design docs.
Proper Thinking
By writing out what you're trying to solve and how you intend solving it, you must have to think extensively about what you want do do before writing code. Many people get stuck building out a feature because they just feel like, "Let's keep writing code and see how it turns out". Writing a design doc forces you to think carefully about your problem first before going to your computer to spill out code.
Future Reference/Guidance and accountability
Here, I'll divide this into two parts explaining the two things I have in mind:
- You'll always have new people who would your team especially when working for a big tech company ( well, I haven't worked in one.. but I've heard). Going through the stress of explaining your thought process to different people over and over again is both time consuming and stressful. Having a place or document they could refer to and read up on the project and the problem it is intended to solve would be a plus both for you and for them ( as they are a liberty to re-read anytime they please to understand something better).
- You'll have those people who comes in the middle of a project and try to change a certain implementation that was agreed upon previously. Having a design Document would help you and all the other teammates in check, because "If you wanted to contribute or have something changed, you could have said it during the review of the design doc, not now!".
What To Include In a Design Doc
- Summary of the feature to be implented.
- Discription of task to be completed.
- Controversial/Contentious issues ( these issues need to be discussed among teammates until a generally accepted pattern of implementation is chosen).
- Additional information you might think is neccessary to mention.
While we see that a Design Doc could be really helpful, we might notice that there are some trouble in using Design Docs. Let's talk about three of these drawbacks ( I got this from watching Clément Mihailescu's video on YouTube where he talked about Design Docs) :
Downsides/Troubles
Design Docs are not so easy to write. Let's face it, doing all those thinking upfront before actually writing code for it, could be challenging and time consuming. These things are what people get better at over time.
Design Docs are not really needed everytime. Where you'll probably need to write these docs the most are at large tech companies where you have so many people on the team, new people come into the team everytime, etc. At a small startup, writing a design doc for every new feature about to be added might be really just time wasting, because everyone literally knows everything they need to know about the feature already, and small talks might just be the perfect fit for these kind of teams in many cases.
The comment sections of these design docs might sometimes turn into a mess where different people just argue or disagree on a particular topic. This could also lead to confusion and demoralisation, as a result implementation might be delayed until these issues are fixed.
That's it on what Design Docs are from me. Follow me on twitter @spillcode for more amazing contents, and tell me if this helped!