Why create a design doc? And why you shouldn’t skip it.
Kevin Moreland, Software Engineer
A design doc can be about a single feature, a set of related features, or about a complete project. A design doc can be very effective as a high-level overview to management and non-technical partners.
The benefits of having a design document:
1. Gets the team on board with an architecture design before coding begins. The idea here is to solicit ideas from your teammates, build consensus, and create buy-in right up through the chain of command.
2. Having a design doc protects your work from other people wanting to switch implementations or change requirements, often derailing the project and/or increasing the overall development time.
3. Having a design doc helps get a project off the ground faster and provides a clear roadmap to completion.
4. If you were the project lead, having a design doc helps you summarize your own accomplishments as a narrative. They tell a story and clarify a body of work.
5. A design doc can be used to flesh out a design among many different people. This includes developers, as well as non-technical project such as managers and product owners.
6. A design doc gives your team the opportunity to discuss concerns now before any work begins. It should be a discussion of design alternatives. When the team signs off on it, this greatly reduces your chances of getting derailed.
7. It allows people who pick up the project later to understand why things were implemented a certain way, or why it was/was not released. Consider updating a postmortem section once you’ve finished the initial phase or release of the MVP.
8. When people approach you with questions, you can point them to the design doc so you don’t have to keep repeating yourself. Tell them “read the doc first”. Tell them if they have more questions after reading it, to come see you. This will save you a lot of time.
9. If you don’t have a design doc, people may start blocking your work because they don’t understand the value you are trying to create for your company or organization. Or, they may be trying to write different implementations of the same idea. Once the team has agreed on a design, you can point your teammates to the doc when they go off on a different implementation. You can ask them…why didn’t you comment on the doc and bring up your ideas before we started coding? You had your chance.
10. Don’t skip writing one — even if you are on a tight deadline.
What should be included in the design doc?
1. At a bare minimum provide a summary…Why are you doing this project and what problem(s) are you trying to solve?
2. What are the project requirements?
3. What options/alternatives are being/were investigated?
4. What are the anticipated tradeoffs and pros/cons for each option?
5. Which implementation are you going to try first (the preferred choice)?
6. If appropriate, list some key data structures, API methods, payloads & responses anticipated.
7. If appropriate, provide simple GUI/front-end sketches, screenshots, etc.
8. If appropriate, provide workflow / architecture diagrams.
9. Can you point to a working proof of concept or prototype as a part of this document?
10. What sorts of experiment are you going to set up?
11. Why types of logging will be implemented?
12. Which option was the winning architecture, and why?
13. What issues were encountered during implementation, and how were they solved?
Put the doc in a collaborative environment and allow comments / edits before any coding has started. i.e. use Google Docs, put it in a Confluence document, etc.
Remember to keep the document up-to-date during development.
After the MVP has been released (or the project fails), ensure the final design document is updated and consider writing a postmortem section.
Other articles on this web site:
- Why you should design for the mobile browser first.
Make a great first impression by focusing on mobile visitors.
- Designing a Server Monitoring and Alerting Service (Cheat Sheet)
A checklist of items when rolling your own server monitoring service.
- Secure Server Implementation (Cheat Sheet)
Creating a secure Java server without using a framework.
- Automating the set up of a Linux-based VPS (Cheat Sheet)
Considerations when configuring a Debian-based Linux VPS.
- Certbot Automation for Java-based Servers (Cheat Sheet)
Ideas on how to automate Letsencrypt's certbot when you are running a Java-based server such as TomCat.
- Automate everything you possibly can, starting with your environment.
Automate everything you possibly can from the very beginning before writing the first line of project code.