To grow to more senior levels, you need to learn to write good technical design docs (also known as “tech specs”). In this article, you’ll learn the most important tips to level up your design docs, no matter your skill level. Exaltitude - SWE Career Development Platform (Partner)
Most of the time, we did both. If we wanted to introduce a new process, refactor something, etc., I first do a Technical Proposal. Later, if it's accepted, I document it in more technical terms in an ADR, also mentioning the proposal, so it's clear why we needed it in the first place.
After reading the entire article I see the second section as extremely important too!
I remember a design review where we had a Principal Engineer in the meeting, yet we were doing a team review and the team was having all the attention. The poor Principal Engineer was just in the background, wasting his time.
In some kinds of documents (e.g. postmortems) the writing style is important. In others, making comments about the writing is just a distraction.
Starting the review meeting and telling people what's the purpose of the review can save so much time
Yeah, that's been a huge "win" for me on leading meetings.
Reminding people at the start what it is we're meant to do. I find that it helps keep things on track and builds confidence from everyone there that we're there to achieve something.
I notice a lot more "This felt productive" comments at the end of the meeting
Awesome write up on design docs or technical specs as I’ve called them. Senior engineers will have to write these, so it’s important to learn what to include and how to write a through doc.
Little things like the “Out of scope” section you included are key to a project’s success.
One thing I would add is a milestones section. It really helps to break a large project down into smaller chunks.
- It allows us to ship incremental value to users.
- Helps us estimate better (smaller chunks are way easier to estimate).
- Gives us a start at user stories and further breaking things out into tickets.
Design docs -> very important for alignment inside the team and also between different teams! Like the idea of getting the individual feedback first. That increases your overall confidence in the spec before you make it public for everyone.
Thanks for mentioning my article from the last week!
The first is a great point and is pretty much the same with PRs. Long ones are either LGTM or take ages to review. 😄
Admittedly, I never wrote such comprehensive design docs, probably because I either worked in smaller teams where we would plan out the thing inside a GitHub issue or because it was client work. In those cases, I was the only one making decisions. But even then, I wrote at least a memo about why I did specific things. Documenting never hurts.
Thanks for sharing this. If everything goes well, I’ll soon present design docs to a bigger team! 🤞
It's cool to hear about your experience and also nice to know we have a similar background too. I've been on small teams a lot lately, so design docs might be a formality in that case after discussing 1:1 with someone.
Still, for the cases where it's not, wanted to have this article for myself and others :D
It happened to me. I forgot why we made a specific decision two years ago, so I also found them helpful in smaller teams!
This article was great for me right now because I'm looking to join a big team soon, and coming from the startup/move fast, break things/ world, I find it helpful to see how things work in the corporate/big team world.
I've found Architecture Decision Records (ADRs) to be a great way to document how and why a decision was reached within a codebase.
Unfortunately, design docs are underrated.
Great post, Jordan! 🙌
I love ADRs too.
Do you do the ADR after the design doc or in replacement of it?
Most of the time, we did both. If we wanted to introduce a new process, refactor something, etc., I first do a Technical Proposal. Later, if it's accepted, I document it in more technical terms in an ADR, also mentioning the proposal, so it's clear why we needed it in the first place.
Ahh, makes sense. Thanks for sharing your approach, Petar
Couple of things I would add to consider depending on project:
- Handling deprecation as part of design doc
- Security and Compliance if needed
- Data related section if needed
Yes, definitely agree Junaid.
I notice many of those sections get added over time to the company doc, normally through postmortem action items to make sure they get considered 😄
Thanks, Jordan for including my comment!
After reading the entire article I see the second section as extremely important too!
I remember a design review where we had a Principal Engineer in the meeting, yet we were doing a team review and the team was having all the attention. The poor Principal Engineer was just in the background, wasting his time.
In some kinds of documents (e.g. postmortems) the writing style is important. In others, making comments about the writing is just a distraction.
Starting the review meeting and telling people what's the purpose of the review can save so much time
Yeah, that's been a huge "win" for me on leading meetings.
Reminding people at the start what it is we're meant to do. I find that it helps keep things on track and builds confidence from everyone there that we're there to achieve something.
I notice a lot more "This felt productive" comments at the end of the meeting
Awesome write up on design docs or technical specs as I’ve called them. Senior engineers will have to write these, so it’s important to learn what to include and how to write a through doc.
Little things like the “Out of scope” section you included are key to a project’s success.
One thing I would add is a milestones section. It really helps to break a large project down into smaller chunks.
- It allows us to ship incremental value to users.
- Helps us estimate better (smaller chunks are way easier to estimate).
- Gives us a start at user stories and further breaking things out into tickets.
- Aligns the team around the main goals.
Totally agree with the milestones section and the reasons for it.
I actually do have that in the list of the various sections--its just not in the screenshot since the document cant fit in a single screenshot.
Thanks for sharing your thoughts around this, Caleb. Love to hear it straight from a tech lead :D
Gosh I read it and missed that. 🙃
Glad we are on the same page!
Design docs -> very important for alignment inside the team and also between different teams! Like the idea of getting the individual feedback first. That increases your overall confidence in the spec before you make it public for everyone.
Thanks for mentioning my article from the last week!
Thanks, Gregor. Well said and totally agree.
Yes! Loved that article. Great writeup on a super important topic
The first is a great point and is pretty much the same with PRs. Long ones are either LGTM or take ages to review. 😄
Admittedly, I never wrote such comprehensive design docs, probably because I either worked in smaller teams where we would plan out the thing inside a GitHub issue or because it was client work. In those cases, I was the only one making decisions. But even then, I wrote at least a memo about why I did specific things. Documenting never hurts.
Thanks for sharing this. If everything goes well, I’ll soon present design docs to a bigger team! 🤞
Yep, agreed on being concise haha.
Thanks for sharing, Akos.
It's cool to hear about your experience and also nice to know we have a similar background too. I've been on small teams a lot lately, so design docs might be a formality in that case after discussing 1:1 with someone.
Still, for the cases where it's not, wanted to have this article for myself and others :D
It happened to me. I forgot why we made a specific decision two years ago, so I also found them helpful in smaller teams!
This article was great for me right now because I'm looking to join a big team soon, and coming from the startup/move fast, break things/ world, I find it helpful to see how things work in the corporate/big team world.
Can you share some good examples?
Of a design doc?
Check the one I did for free subscribers here: https://jordancutler.notion.site/Technical-Design-Doc-TDD-Example-24061060c5e1412684d1430584e8ef75?pvs=4