A Design Doc Is Not A Checkbox
Building software that is ready for a production environment is hard. Solving a problem by writing code includes trade-offs to consider when there isn’t always a definitive answer. As such some software projects these days start out on an empty piece of paper or Quip document. Writing out ideas in a design doc helps answer key questions such as what are the goals of the project? What solutions will help me achieve those goals? What are the trade-offs to consider? Do I have to work with any dependencies? What does my team think?
Senior engineers should be setting, if not raising, the bar for their team by showing what a good design doc looks like. Junior engineers will follow their lead by writing design docs of their own when starting a project. However, when it comes to presenting their document, some junior engineers may treat it as a checkbox, or something they need to do to unblock themselves from writing their first line of code. Instead of treating it as some obstacle to overcome let’s understand why a software engineer might start a project by writing a design document and the takeaways from this exercise.
Brainstorming
The act of writing provides you with the opportunity to brainstorm ideas. One idea may lead to another idea or perhaps call out a trade-off to consider when comparing ideas. Often times the ideas that you come up with during the brainstorming phase of the writing process are vastly different than your original ideas.
This process can help you uncover more to the problem or raise questions which will better help you understand the problem. By writing down any open questions you’ll be able to answer them for yourself later or use them as a starting point when discussing your project with members of your team to get their insights.
Perhaps after brainstorming ideas, you’re not convinced you have the right solution, or even how to weigh the trade-offs of the solutions that you do have in mind. This exercise has at least helped you better understand the problem and start to form some opinions. Presenting what ideas you do have will allow you to share your thinking so far and allow members of your team to help out in the problem-solving phase of the project. When you’re working with a team it’s important to not feel like you’re alone when trying to address a problem. By being able to present a document with background information and your research you will be able to effectively communicate your ideas, so that you’re able to get meaningful input from others quickly.
Diving In
Have you ever started coding a project and realized that your idea isn’t as straight forward as you once thought? With some projects you may start out with a high-level idea of what implementation would look like, but when you dive in, there aspects of the problem that you forgot to even consider. Writing out the approach you will take to how you would solve the problem will help you both find and address these flaws that you would have found during development. Doing so will allow you to course correct early which will make the development process a lot more straight forward.
If I find that I’m not able to speak to certain details about a solution or it’s not clear how I will get to the target end state, it’s a sign that I need to do more research or brainstorm alternative solutions. One of the tools I like to use to help me understand the details are sequence diagrams. Sequence diagrams can help visualize interactions between different components to help enrich your understanding and allow you to communicate your ideas in a visual manner to your team.
Influencing
A well-written document will allow you to share ideas with others without having to explain it multiple times. How many times have you tried to explain an idea only to be interrupted with a question? Or worse, how many times have you finished explaining an idea only to find out you lost your audience? Explaining technical topics to others is difficult if your audience is not already familiar with some of the underlying ideas that your project depends on. By presenting a written document your readers are able to follow along at their own pace. As they read, your readers may have a question only to have it answered later on in the document. That’s one less interruption that you’ll have to deal with when presenting to a group.
After successfully communicating your ideas to your team, it’s time to get their buy in. By including alternatives considered, each with their own sets of pros and cons, it will help your readers understand your decision-main process and how you are prioritizing trade-offs. Sometime it’s helpful to include a set of tenets which directly address how you are prioritizing trade-offs in your decision making. If keeping data secure is your number one priority, then state it as a tenet. This will help rule out any solutions that violates this tenet. By succinctly presenting your ideas, it will help you get buy-in from your team and help you steer the technical direction of your team.
Moving Forward
A design doc is meant to ensure you’re building the best-known solution for a problem with a given set of constraints. At what point do you move forward with actually writing that first line of code? It might first help answer the question “Who is the decision maker?” I recently finished the book “What You Do Is Who You Are” by Ben Horowitz. This book discussed the three types of decision makers. The first type of decision maker makes the final decision despite what anyone else thinks. While it allows a single person to make decisions fast, they may not always be the best decision. This type of decision maker doesn’t work well on a team as they may make others feel like their opinions don’t matter. On the other side of the spectrum you have the democratic decision maker which aims to get consensus from the entire group. While this approach may make for better decisions and will make the team feel included in the process, it takes far too long to make a single decision and therefore reduces decision velocity. Somewhere in the middle the owner of the document listens to and addresses feedback from their peers, but ultimately owns the final decision. This ensures others feel like their voices are being heard and part of the decision process. This approach is a good balance between speed and landing on the right decision. As a junior developer, you may not be sure when to move forward after presenting a document and receiving feedback. In this case partnering with a senior engineer or your manager can help you make that go or no-go decision.
Alternatives
Writing isn’t for everyone. Even then, you may run into questions in your doc that can’t be answered from research or debate. Instead some people may want to jump straight to the coding to test out ideas or to better develop their intuition. Building a prototype is a great way to figure out what ultimately needs to be built. A prototype can be hacky and not ready for a production environment, but at least demonstrates how a problem might be solved. It doesn’t have to solve every edge case or be fully optimized, but it may help provide data that normal research is unable to provide. This can ultimately influence the strategy of what is built and sent to production.
Conclusion
At the end of a day a design doc is a tool to help make high quality decisions and allows you to effectively communicate your ideas with other project stakeholders. This allows you to incorporate feedback and ensure you’re both solving the right problem and making the right tradeoffs before you write your first line of code. After all, it’s a lot faster to change an idea on paper than it is to change an idea in code.
