Simple tricks to level up your technical design docs in 2024 👌

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.

Getting promoted to more senior levels requires more skills in docs

Exaltitude - SWE Career Development Platform (Partner)

Jean Lee, the 19th engineer at WhatsApp runs a career development platform for software engineers—Exaltitude.

Jean and I are partnering to share our knowledge across audiences.

She shares top-notch advice for growing in your career or landing a job.

Here are some of her links: Blog, Job seeker resources, YouTube Channel.

⭐️ Main takeaways

• Why design docs are useful and how they help you

• Actionable advice for making them 5x better

❓Why design docs help you

1. Reduce risk

2. Document why decisions were made

3. Align on important technical decisions

🎁 Bonus: You can reference them when making a promotion case. Design docs show the project had sufficient complexity and scope. If you skip it, it can show the inverse.

When writing the design doc, you will frequently wonder, “Should I include this?”

Use those 3 reasons for the design doc as guiding principles.

If anything you include doesn’t move those forward, you probably can cut it.

👌 (1) Keep it concise

Avoid the long scrollbar.

Keep only what is needed to make a decision on a path forward.

If your doc is too long, it won’t get read.

If it doesn’t get read:

1. Your doc stays in review for ages. This makes you look like you aren’t driving progress forward. OR

2. Your doc moves forward with feedback that isn’t thorough. This raises risk and comes back to bite you when problems arise.

Fran Soto, Author of Strategize your Career explaining the purpose of a design doc

In practice, this means not overly documenting every individual ticket that needs to get done and how it will get done.

Instead, focus on the API contracts and interfaces.

• API route data changes

• Data models

• Database schema and indexes

Finally, include information on particularly complex pieces with higher risk, that you need more eyes from the team on to ensure it’s the best approach.

🤝 (2) Get individual feedback first

You want to get feedback from the most vocal reviewers individually first.

After you’ve got their feedback built into the doc, schedule the group session.

With this, your group feedback session becomes more like a formality.

The best cases I’ve had of a group review session are when I start the meeting with:

“So I know I’ve spoken to each of you individually about the doc and we’ve gone through some async feedback. Thanks for all the feedback. This meeting is to allow us to discuss any remaining feedback in a group setting.”

Lauren Darcey, Senior Eng Manager at Slack suggesting the same.

Steve Dwire, Chief Technical Architect, also agreeing

Doing this gets those vocal reviewers bought in to your doc because you incorporate their feedback early on.

This makes the group sessions smooth. That makes you look good.

3) Don’t just “fill it out.” Understand “why” each section is needed

Here is the template I recommend and the why behind each section.

This is a little lengthy but worth the read for higher-level thinking.

1. About this doc

   1. What it has: Status of the doc and signoffs needed to move forward.

   2. Why: Make it clear right away whether this doc still needs work to move on.

2. Context

   1. What it has: Problem being solved and the impact.

   2. Why: Understand why this is being worked on.

3. Out of scope

   1. What it has: What will not be part of this project.

   2. Why: Avoid scope creep by explicitly calling out what will not be included.

4. High level approach

   1. What it has: Overview of how you plan to approach the problem.
      Note: I recommend including a visual of how the feature should work from a user perspective and/or a diagram of your data flow here.

   2. Why: Allow people to skim the doc and quickly understand your approach.

5. Alternatives considered

   1. What it has: Alternative technical approaches you considered.

   2. Why: Document decisions on why we aren’t going with another approach. This helps when the question comes up 1+ year later. Also, make it clear the approach we are going with is the correct one.

6. Technical Design Requirements

   1. What it has: High level requirements from a technical perspective to support the user use cases.

   2. Why: Make it clear before jumping into the detailed design why the detailed design is needed from a technical perspective. Note: This is a section I have added that I rarely see in design docs but I believe is valuable.

7. Detailed design

   1. What it has: The API, interface, model updates and anything complex.

   2. Why: Agree on the essential pieces of the code updates: The contracts.

8. Risks

   1. What it has: Ways the project may not achieve its goals and how to mitigate.

   2. Why: Reduce risk by thinking of it ahead of time and calling out mitigations. Show your reviewers you are thinking of this so they gain more trust in you.

9. Test plan

   1. What it has: How the solution will be tested to ensure it works as expected.

   2. Why: Reduce risk by thinking ahead on how it will be tested. Improve accuracy of your estimate—since many estimates forget about how much testing goes into productionization.

10. Milestones

    1. What it has: Timeline breakdown of key achievements.

    2. Why: Reduce risk by breaking down the project into smaller deliverables.

11. Rollout plan

    1. What it has: Timeline breakdown of rollout to customers.

    2. Why: Reduce risk by gradually rolling out to customers and aligning everyone on the plan.

12. Open questions

    1. What it has: Open items to be answered. Move into the doc after answered.

    2. Why: Explicitly call out what still needs to be answered to move forward. Allow more senior folks on the team to jump in and help.

13. Parties involved

    1. What it has: The people involved in each key part, like the product manager, other engineers, primary driver, designer, etc.

    2. Why: Reduce risk and create alignment by ensuring everyone is on the same page about their responsibility moving forward.

14. Appendix

    1. What it has: Diagrams that may be too large for the main area of the design doc or were referenced multiple times.

    2. Why: Ease of reading where applicable, if particular diagrams are referenced multiple times or are especially large.

This is a much more complete version of a design doc. For smaller features, you can delete some of these sections and keep them more brief.

Now that you understand the reason behind each one, you know if it can be deleted.

I have a full template available for paid subscribers. Here’s how it looks:

Technical Design Doc Notion template

📖 TL;DR

Here are the main reasons for design docs:

• Reduce risk

• Align on a decision

• Build trust with the team

• Bonus: Use them as documentation for promotion cases

You can probably remove any part that isn’t working toward these.

Here is how to make your design docs better:

1. Only include as much technical detail as needed to make a decision. Be concise.

2. Involve reviewers individually before meeting in a group setting.

3. Follow a template but know why each section is there. Avoid just “filling it out.” It’s particularly important to always include “Risks.”

📣 Shout-outs of the week

• Recommended newsletter: Pointer.io - It’s read by 34k+ engineers and is highly curated to give some of the top articles in the industry that week.

• Podcast feature (Junior → Mid-level): I was featured on a podcast this week! We shared a ton of actionable advice on going from Junior Engineer → Mid-level Engineer. If you’re just starting in your career, this video is for you! Here is the Spotify podcast link too.

• Keep a brag list of the wins you achieved on

  Engineering Leadership
  by
  Gregor Ojstersek
  —Fantastic article on a high leverage activity all engineers should be doing to support their promotion.

---

Thank you for your continued support of the newsletter and the growth to 44k+ subscribers 🙏

- Jordan

P.S. If you’re interested, here’s a few other things you may be interested in:

1. Path to Senior Engineer Handbook (7k+ stars)—Everything you need to get to Senior

2. My LinkedIn: I write daily content to 45k+ engineers. I’m also ramping on Twitter/X

3. Newsletter sponsorships: Feel free to reply to this email or check the Sponsorship packages

Did you find this issue valuable? If so, there are two ways you can help:

You can also hit the like ❤️ button at the bottom of this email to help support me or share this with a friend. It really helps!