Taro Logo
1

How to get better / speedier at design docs?

Profile picture
Mid-Level Software Engineer at Taro Community15 days ago

It might be a very broad question, but how can I be better at writing design docs? At my current stage, I can get parachuted into a new package, implement a feature and fix some random things on my way out, but I struggle to write design docs. For context, people in my org really drill into the design docs and most of the questions are not really relevant. ~40 people would leave comments on a doc on average, which seems on the higher end across the industry, right?

My struggles with design docs are mostly,

  1. Difficult to start working on it because I don't really like writing essays
  2. Analysis paralysis that I want to have it perfect, but it's just not possible due to all kinds of observability issues (e.g. missing log fields)
  3. It's unclear what the project is about so it requires lots of discussion, which takes initiation / social energy
  4. Maybe some PTSD for just working with people and trying not to lose my patience

The solution to my struggles might be easy - like just get started and don't try to be perfect. Treat the design doc as a discussion instead of a one-shot event. What's your approach to design docs?

On a higher level, I can utilize my strength in coding and try avoid design docs, or I can improve on writing design docs. Which option do you think is best?

57
6

Discussion

(6 comments)
  • 2
    Profile picture
    Tech Lead/Manager at Meta, Pinterest, Kosei
    14 days ago

    First, I advise going through the Frontend System Design Masterclass - Building Playlists, which is a great example of a thorough design doc.

    One tactic in particular to overcome the analysis paralysis you mentioned: when you're starting, remove any notion whatsoever about perfection. Just put words on the page, anything you can think may be relevant to the project.

    Giving yourself permission to just word vomit is the most effective way to make progress. Once you have the doc, I also find it easier to take the next step of cleaning it up or sharing it with others.

    As you become more senior, your impact will increasingly come from your ability to write well, and design docs are a big part of this (along with status updates, executive summaries, postmortems, etc). So I definitely would not avoid this skill.

    How can I write a great design doc?

  • 1
    Profile picture
    Tech Lead/Manager at Meta, Pinterest, Kosei
    14 days ago

    ~40 people would leave comments on a doc on average, which seems on the higher end across the industry, right?

    40 people is really, really high. Unless this is the biggest project in company history, it feels like overkill.

    Historically at Pinterest or Meta, my experience has been that 3-4 people will comment on the doc. It'll be accessible to everyone, but < 5 people truly go through the doc in detail.

    • 0
      Profile picture
      Mid-Level Software Engineer [OP]
      Taro Community
      14 days ago

      Yeah that's my experience in my previous team as well. The team is about 10 people and roughly 3-5 people would leave comments on a doc, which is 30-50%. My current team is 20 people. Usually one project needs to involve 2 external orgs, each of which is about 40 people. That's 100 people. Extrapolate with 30-50%, we got 30-50 people leaving comments

      Most of the comments are just clarification comments, so it's not moving the projects direction, which makes alignment slightly easier.

    • 0
      Profile picture
      Mid-Level Software Engineer [OP]
      Taro Community
      14 days ago

      I'd just think I'm playing the hard mode for design doc review. When I move out the org or company, life will be easier.

  • 2
    Profile picture
    Eng @ Taro
    14 days ago

    people in my org really drill into the design docs and most of the questions are not really relevant. ~40 people would leave comments on a doc on average, which seems on the higher end across the industry, right?

    That is a pretty high number, but it's great that people are that enthusiastic that they want to leave comments. Most of the time, you have to really prod people to leave comments. Although, I would focus on addressing comments from a core group of more experienced stakeholders.

    Difficult to start working on it because I don't really like writing essays

    I would try to tackle the design doc in the most low-stakes environment possible to get started. This might look like a bullet-pointed list in your personal note-taking app where you are writing down your initial thoughts. If you are uncertain about something, just write it down and add a question mark at the end so you can revisit it later.

    The momentum of just writing something down will carry you through to proofreading and fleshing out more of your less refined points.

    Analysis paralysis that I want to have it perfect, but it's just not possible due to all kinds of observability issues (e.g. missing log fields)

    This usually happens to me when I try to keep too much information in my head. I start to dwell on all of the possible decisions that can be made and worry about whether I'm missing something or making the best decision. It's easier to just lay out your entire thought process on paper and tackle one problem at a time.

    For points that you want to refine further, you can sprinkle some TBDs throughout the document and do a deep dive into them later.

    It's unclear what the project is about so it requires lots of discussion, which takes initiation / social energy

    I would start with deciding what you believe the goal of the project is and then fill in the steps needed to reach the goal. Give it a first stab based on what you think is correct.

    If the project is so unclear, you might want to talk to a tech lead or manager about the project over a casual chat to make sure you are going in the right direction.

    And, of course, it doesn't have to be correct/perfect the first time. Maybe the social dread comes from having people critique your work? I would try to reframe the design doc as something that's a work in progress which will get better and better with collaboration with your colleagues.

    On a higher level, I can utilize my strength in coding and try avoid design docs, or I can improve on writing design docs. Which option do you think is best?

    I do think that writing design docs can help to progress your career because it teaches you how to collaborate with different stakeholders to and how to make the best decisions when confronted with uncertainty. It's these ambiguous situations where you have to make decisions with multiple tradeoffs that no one wants to make which can really help you grow.

    • 0
      Profile picture
      Mid-Level Software Engineer [OP]
      Taro Community
      14 days ago

      Thanks for the very thoughtful answers. I'll take another read to absorb it better