So what is a technical design document?

A technical design document is a powerful tool in the software engineering tool belt. I like to think of a design document as a blueprint, a plan for your software projects. Imagine, if you were to build a skyscraper in New York City, you wouldn't just go and build it. You can, but that's just silly. Silly because it is a large and complex project that requires planning to have a successful execution. Similarly, technical design documents let you plan and execute on software projects, both small and large.

If you work in a team setting, building software without a design doc can be wasteful and dangerous. Imagine, you start building without a design doc. There's always a chance that some other engineer from your team will come with different ideas and start questioning why things are done the way they are. He could even propose a better alternative that's simpler and costs less. Then your entire work might become a waste of time quickly. That's why design docs are important and they should be created in a collaborative environment. Try Dropbox Paper or Google Docs to write your next design document.

Design documents can help you plan small and large ideas, align teams and stakeholders, and make it easier to execute on them. So you don't waste time later. Usually, a design document is driven by a business need (e.g., new feature development) or a technical need (something is broken, here's a solution). It describes in detail a solution to a given problem.

Design documents also serve as technical documentation. When teams change, such documents can act as a source of truth for design and implementation decisions. For the current engineering team, it is a useful implementation reference.

One of the reasons I like design docs is that they offer a place to discuss alternatives. Often there can be several ways to arrive at the same solution. Weighing pros and cons is a great way to come to the solution that seems right at that time, and ensure that the ideas of other team members are taken into consideration.

Let's take a quick look at a typical structure of a design document. Remember, these documents can take any shape or form. My design document usually has the following sections:

  • Overview. Here I describe what this document is about and what problem it is trying to address.
  • Technical part. This is the meat of the document. It describes the solution in detail and addresses any alternative designs.
  • Milestone and work estimates. This section describes the execution plan. It is useful to break down larger bodies of work into smaller size deliverables.
  • References. Additional reading material. This is a good place to refer any existing design docs that are relevant to this project.

There's one more thing I want to cover. Design docs are living documents (to some extent). If something needs to change and does not go according to the plan, change but don't forget to update the doc. It is a good practice to come back to the document after the feature, or a project was delivered and document the results. Did the performance increase as it was promised? Capturing the results will close the loop of the project. All decisions and results are documented in a single place and easy to reference.

There are mixed feelings about design documents. Some people think that it's a complete waste of time. Others, can't do anything until they have one. Both sides are correct. It all depends on the size of your company and the complexity of your project. However, in most cases, it is always better to have a design doc than not. If you don't have a design doc right now, you can write one retroactively. Even if you ares small now, it does not mean you will always stay the same. When your team grows, you will be glad that such docs are available to reference.