Foundation is Key: The Software Design Document (Part 2)

In my previous post, I talked about the fundamentals of a software design document. In this post we will answer one very important question.

Why?

According to Angela Zhang, “A design doc is a description on how you plan to solve a problem. It is the most useful tool to ensure the right work gets done.” That is the definitive answer to why your team needs this document to start, plain and simple. It is one of the most important tools in your design arsenal. It will force you to think critically about your project. It will help you plan out everything you and your team needs to do to make the project effective, and with the right scope, will cut out the fat. It keeps your whole team on the same page. It says “This is everything you need to know about the project.” As I stated at the start, it answers all of the questions and gets you and your team working together to develop without a doubt.

Here is a Thought Experiment…

Think of a project right now that you want to get done with a small team of 5. You don’t want to write a design document; you think you know everything about the project and what you all need to do to complete it. You delegate tasks to your team after a drawn-out and aimless meeting with a bunch of “um”s and “ah”s. Maybe the team goes off-topic at one point while you’re thinking about anything else that could be important. The team asks you questions and you pause to answer them. Some of the questions may even be left unanswered.

You all start to brainstorm and answer questions about the project as a team. You make a large list of brand new and awesome-sounding features this software can do. Everyone is more hyped about this project than ever, and you truly believe to yourself that your amazing mind-blowing project can change the world! And it just might. With everything proposed in an improv manner like that and quickly scribbled in those meeting notes, your first prototype could have an above-0 chance of changing the world if and when it’s completed. However, I wouldn’t bet on this type of project succeeding, let alone completing in time.

Some of you may attribute this to me being a Debbie Downer just to strengthen the point I’m driving home here, but this isn’t the case. The reason why isn’t pessimism; it’s realism. I have made this same mistake before. I’ve done it with my own design teams. I’ve done it on my college final project. I’ve even done it to myself on personal projects. What happens next is almost a prophecy of failure; time goes by while you’re working on the new features with the team. You direct the project with an improv-style, adapting to bugs as they come, starting and stopping on different aspects. Eventually the deadline comes, and your team showcases what you initially planned with the team to be a success, only to see it not entirely doing what you envisioned initially.

Have you ever had that feeling when you wanted something, worked for a long time to get it, and once having it in your hands, you have no idea what you wanted in the first place? A meeting like the one I’ve described, without a design document, will most likely end up in this manner. The reason why it does is because the document gives the team important elements such as direction, prioritization, answers to questions, and an overarching plan.

…With a Design Document.

Let’s travel back in time to before the meeting even starts. You’re on your computer with a blank document in front of you, and you are typing out the name of the project. Nobody is around to judge your decisions; you can sit comfortably as you flesh out this project and what it does. You list who is in charge of each aspect. You list all of the classes in C# the project will need and what they do. You define what this software will run on. You answer whatever questions you have in mind, and you dial back the scope. The bare minimum is on this document, and you are ready to show it to your team the next week.

Monday comes and you show your work to your teammates. You hand a copy of your document to everyone so they can read along. Everyone is aware that this is the base software, they know what it does, and they know what they have to do. Most importantly, they all know they have six months to see it to completion.

You get to brainstorming improvements, listing everything the software will need to be even better than what is at the base level. You sort it out by what is realistic, but assert that the main functionality comes first. Nobody assumes the program does anything else. You delegate the most important tasks to the right people as your team creates the prototype. About five months later, your team has not only completed the project, but you have a week to add the new functionality! Your team polishes the prototype up, and you all begin work on improvement.

Let’s say that not all of the cool features could be added. Maybe one or two got added and you were halfway through the third one. That is okay, you rolled the project back to its 1.1 version before you brought it here. Your benefactors are impressed with the base project. It does what you said it would do and it does what they asked for. Your team went above and beyond with the final product. Obviously, this wouldn’t happen exactly as I’ve described it. There are other varying factors with a real project, but this scenario assumes you know your high concept along with what your team can do, and they are able to do it.

Do you see how one small change can affect the entire development process? Typing up that design document before the meeting has given you the time to think of every detail you need to make the base software. Before the meeting even started, you laid out all of the risks, all of the necessary functions, the goals, and removed any doubts or questions the team had before they even asked. You gave your team direction, and thanks to your document, you and your team had something to fall back on so there was little room for deviation.

Conclusion

In short, the Software Design Document is your team’s guide to better development on any project you have your sights set on. It’s your project’s bible; what it says goes, and all of the big questions have to be answered in this document before you write a single line of code. When making one, A.S.S.E.S.S. your team’s abilities to plan a Minimal Viable Product, then iterate in the bells and whistles later. When doing so, you ensure the right work gets done! Without this document, your team will likely deviate and prioritization can be mismanaged. With one, your team will be more focused on what the project needs, because everyone will be on the same page about it.