A design doc — also known as a technical spec — is a description of how you plan to solve a problem. It’s one of the most useful tool for making sure the right work gets done.

It’s just more overhead man..⌗

🤷‍♂️ people often claim that it’s because they’re saving time by skipping the spec-writing phase.

But what they don’t realise is that in the long run (even for a smaller project that’s true), they might be spending a lot more time fixing, iterating and communicating all the same stuff (over and over again) what they could have done once if they had written a proper spec for it.

Joel Spolsky (@spolsky) has written [quite extensively] about this in his article.

So, why does it matter?⌗

A well-structured design doc can save you days, or even weeks of wasted time!

The main goal of a design doc is to make you more effective by forcing you to think through the design and gather [early] feedback from others.

Point is that when you design your product in a human language, it only takes a few minutes to try thinking about several possibilities, revising, and improving your design whereas when you design the same product in a computer language, it takes weeks to do iterative designs / changes.

Another big reason of having well-written design docs is that they save us time communicating the stuff by making sure that everyone is on the same page, and that can help us build great products and innovate quickly. Everybody on the team can “just read the spec”.

What happens when you don’t have a spec is that all this communication still happens, because it has to, but it happens ad-hoc..

How do I go about writing a design doc?⌗

Umm… I won’t go into too much detail. There are already several good articles on the internet that does that. I’ll try and summarize the points (and maybe add a few from my side) into the following list -

  • Try and stick with high-level overview without diving too much into implementation detail
  • Define what service you’re building and what are the objectives
  • Provide a context to the readers, describing where the service fits in the overall architecture
  • Outline goals and non-goals of the service and make them quite explicit
  • Give a high level technical overview. Use user / case stories to depict scenarios
  • Highlight your dependencies (what other services your service will depend on) and tell “why”
  • Describe your choice of stack (but don’t dive too much into technicalities) and the reason why you chose them
  • Highlight any potential issues / open questions and get feedback from peers
  • Add links to other sites, references or articles that might be helpful
  • Get feedback early-on rather (and perhaps on each step)

I personally found that following ☝️ steps is generally very helpful and makes one more productive than doing it the other way

References⌗