#7 - Design Docs

Companies reward those who write great design docs. As they should. Here's 5 areas to focus on when you write your doc.

Hey everyone,

I’m extremely excited to write this week’s newsletter. A lot happened last week!


  1. We crossed 200 subscribers 🥳

  2. We kicked off “Summer of Shipping”! A program for students who had their summer internships cancelled (or just want to build). 30 live Zoom participants and another 70 views on Youtube 🚀

The story of “Summer of Shipping” has come together quickly. Here’s a recap:

  • A couple weeks ago, I proposed a “Build Together” initiative where we would start an open source project and build together. A byproduct of this would be code reviews, which I would later analyze for the newsletter.

  • Last week, I realized that internships were being cancelled at an alarming rate and pivoted to “Summer of Shipping”. A couple people signed up.

  • On Tuesday, I posted to Reddit. Many people signed up

  • On Thursday, we had our kickoff

  • By Friday, we had set up a Discord and a Twitter account

If you know of any students who had their internships cancelled, or just want to build with us this summer, please check out this form: https://forms.gle/3N3CfqbH6YkM1DF67 (and share!)

So those are the updates!

Alright, let’s dive in to today’s topic - design documents.

Design Docs

If you can write a good design doc, you’ve got a skill that’s highly coveted by companies. Many engineers at large organizations have realized you can win the promotion process if you have a successful, business-sensitive project to your name, paired with a killer design doc.

So what’s a design doc?

Design documents are a nebulous term that generally refers to a document that is written before work begins. It outlines the problem, explores solutions, and details the chosen solution. At large organizations, design docs also must satisfy a laundry list of considerations before it’s considered complete (security, privacy, PII, legal, etc.).

Many young engineers hate this process because it feels like a lot of wasted effort and bureaucratic red tape. And they’re not wrong. A large percentage of the work is indeed wasted. But the small fraction that ends up being useful can be the difference between success or abject failure.

There are lots of resources that tell you what you should put in a design document (i.e. excellent blog post from Range). These tell you how to dot you “i”s and cross your “t”s.

I won’t do that. Instead, let’s focus on 5 essential bits of design docs. Time spent in these areas have the highest ROI.

1) Problem Definition

It makes absolutely no sense to solve a problem if you haven’t identified the problem. Don’t make a key 🔑 if there is no lock 🔒

When it comes to a design doc, it’s often assumed that the problem is a given - that it is something we should be doing.

A good problem will galvanize readers to action. Teammates want to hop aboard. Managers want to give this project every resource available. A good problem definition provides clarity and sparks enthusiasm.

But when you write down your problem, you might feel like the problem statement comes out a bit flat. In fact, you might even wonder “Is this even the right problem to solve?”. That senior engineer might be excited about building this, but now that you’ve written it out, should we really proceed?

This might just be the most important question you can ask. So don’t turn off your brain when you write the problem definition. And make sure you’ve got an electrifying problem statement ⚡️

(And if you’re wondering, yes, the subtext here is that this has happened to me. One time I didn’t push a senior engineer about why we were trying to solve 3 problems at the same time. It seemed like 2 of them were 10x more important than the third, but the third expanded the scope by like 2-3x.)

2) “Maximize the Solution Space”

I can’t put it any better than this comment from HN:

Make a list of possible solutions. Write all the solutions down. The good ones and the bad ones, don't think about it just write write write write. Then add some more (what if you didn't write any code? What if you had to ship in 48 hours? what if you had 2 billion dollars to throw at the problem). Your goal is to maximize the solution space you're covering so you don't get stuck at a local maxima. You want global maxima.

If your design doc has only 1 potential solution, then you need to keep going. The chance that you found the best solution is extremely low.

Get more solutions. (No need to do a full writeup of each one, just enumerate)

List the good ones and the bad ones. Just write write write!

3) Architecture Diagram

Now that you have a list of solutions, one of them will emerge as the winner (it might actually be a mashup of a couple solutions).

Take the winner and diagram how it will work. Draw out how all the components talk to each together. Use arrows to help readers visualize the flow of data.

A design document is incomplete without a diagram. A diagram helps readers learn your solution. It also assists with memory, as a simple glance of the diagram will keep the solution fresh.

Here’s a random example from Cockroach DB:

I’m not really sure what this diagram means because I’ve never studied CockroachDB, but I’m sure it was useful for the original collaborators to divide up work and for them to onboard new contributors.

4) Data Models

The hardest part of a system to change is the data. When it’s just you developing on your local machine, you can wipe the database every 4 hours and it’s not a big deal. Once you have users, you’ve got a baby on board. Now you’re responsible for that data. Changing code is easy, but changing data is a huge pain.

And not only are data models hard to change, they often dictate so many flows in your app. They will shape the way you think about your problem space.

Devote a disproportionate amount of time on designing data models. Get as much feedback on them as you can.

5) Interfaces

Let’s say you have two modules, A and B.

A depends on B.

A beautiful idea in software engineering is you can start work on A, before B is even done - if you first define and share the interface between A and B.

For example, if you’re working on a Java project, the two sides can agree to an interface file, which can be written and committed to the codebase early on. Both teams can develop against that interface without one blocking the other. Same is true in any language that offers interfaces.

But this extends outside of the scope of the project and to the level of your application boundary - namely, your API.

Like your data models, your API can have a massive impact on your project. A good one will allow for combinatorial new uses of your service. A bad one will trip up your team and allow a competitor to swoop in and pluck all of that low hanging fruit.

Spend a lot of time on your interfaces. It will pay excellent dividends.


Design docs matter, but they can be grueling to complete. I want to help you stay motivated when you write one and focus on the critical areas:

  1. Problem Definition - write it down, challenge it. Saying “won’t do” to an unimportant problem is the highest ROI activity you can do. Make sure it energizes you to read it

  2. “Maximize the Solution Space” - explore with reckless abandon.

  3. Architecture Diagram - Once a solution has been picked, diagram the architecture. A good diagram has massive ROI in terms of project management

  4. Data Models - hardest thing to change, so be relentless in your search for feedback

  5. Interfaces - Focus on your internal interfaces (between modules or internal services). Focus on your public APIs.

I want to leave you with a concept I love. It comes from the 7 Habits of Highly Effective People and it’s the idea that in anything we do, there are actually “two creations”. First in the mind, then in reality.

If you aren’t clear about what you want, then your result will be the byproduct of everyone else’s actions. In software, this means a discombobulated system of dissonant styles, functions, and data types. In other words - a mess.

A design doc is that first creation. In all the best projects I worked on, there was a crystal clear 💎 design document that we executed against beautifully (although, the projects took 10-50% longer than anticipated 😝). In the worst projects, the design doc was an afterthought 💩 (and took 100-infinity% longer 😱).

Until next time,


PS - I know I promised a technical post this week, but I felt it was important to write this post earlier in the summer as opposed to later, for the benefit of “Summer of Shipping”. We’ll bite off some meatier topics soon! Also, developing a good attitude towards design docs makes you “more senior”