Design Docs ✏️
Why they are the most important tech docs, and tips and templates to create great ones.
Writing docs belongs to that category of dev tasks that everybody knows they should do, but nobody wants to do anyway.
It’s an exclusive club with other illustrious members, such as writing tests, estimating tasks, or updating JIRA.
The natural restraint towards such tasks is often dismissed as laziness. But laziness carries meaning.
When devs don’t want to do something, what they are really saying is:
It’s a hassle — high cost
It’s not worth it — low value
People have a small ROI calculator in their head, which is saying that the ROI is negative.
This version of laziness is useful and has driven important conversations in the past:
Tests — many teams today write less unit tests in favor of more integration tests. We went from the testing pyramid to the testing trophy.
Estimates — we spend less effort on estimates than in the past. T-shirt sizes and story points often replace man-days, being both lighter and more manageable.
The goal of this article is to have the same conversation on tech docs to make them 1) less of a hassle, and 2) more worthwhile.
This is what we are going to cover:
📖 Types of tech docs — the three main ones.
✏️ What are design docs — and why you should write them.
📋 Structure of a design doc — my own template based on three areas: essentials, disclaimers, and reminders.
❓ FAQs — maintaining docs, involving stakeholders, and deciding when docs are not needed at all.
📚 Resources and case studies — how design docs are managed at companies like Google, Plaid, and others.
The article also includes ideas and insights from members of the Refactoring Community, like:
Andrew Twyman, former Staff Engineer at Dropbox
Zach Wolfe, Senior SDE at Amazon
Let’s dive in 👇
📖 Types of tech docs
This is the first source of confusion. Many times you hear people asking “do we have the docs?” — but what docs?
It is useful to organize them into three main types:
Functional spec — the product requirements. To communicate what should be achieved from the user perspective. It includes UI/UX specs.
Design doc — the tech design and implementation strategy. To record decisions, communicate trade-offs, and converge on a solution.
Tech spec — API specs, database schema, and the overall description of what’s live.
In my experience, everybody understands the difference between the product and the tech stuff — that is, between the first type and the other two. It is easy because those are usually created by different people: PMs and designers on one side; engineers on the other side.
On the contrary, the difference between design docs and tech specs is tricky.
In my opinion, 80% of the time what you really need is a design doc rather than a tech spec. That is, you need to record your decisions rather than describe what’s live.
To understand this better, let’s cover what design docs are and why you should write them.
✏️ What are design docs
A design doc illustrates the tech design and implementation strategy for a given initiative.
It is meant to be created before you start writing code, and to be shared with other stakeholders to converge on the solution.
You write it for several reasons:
💭 Help your reasoning — writing is thinking. Going through the process of writing a formal document helps solidify your reasoning and come up with a better solution.
🔨 Improve the design — find the best solution through the contribution of others. Like a code review, but for the design.
🤝 Create consensus — align with stakeholders about what should be built, make sure important decisions are participated, and make people feel invested in them.
📓 Record the decision — for posterity and documentation. That includes the trade-offs you evaluated, alternative solutions you discarded, open questions, and more.
In that respect, a design doc is useful throughout the whole lifecycle of a project.
Before release — it drives the process that makes people converge on a good solution.
After release — it acts as a decision record, that is often more useful than pure tech specs.
So, what goes into a design doc? 👇
📋 Structure of a design doc
You should have a template with all the sections you may want to include in the design doc.
You won’t need all sections all the time. Consider them a checklist: you go through it and fill in what’s needed.
In my head, sections are organized into three main categories:
🎯 Essentials — things you should always include, like goals and tech design.
📝 Disclaimers — things that create alignment and guide the conversation.
⏰ Reminders — things that “let’s make sure we don’t forget them”. And boy, there are many.
Let’s see them 👇