Taro Logo

How to improve on non-technical skills like writing Software design document?

Profile picture
Mid-Level Software Engineer [62] at Microsofta year ago

I am good at coding, and I am able to deliver features to prod. However, when it comes to technical writing, like writing software design document, coming up with state transition diagram, block diagram, I am struggling with it a lot. I am not from computer science background, so I am not well versed in coming up flow chart, sequence diagram and state transition diagram. How to improve on these areas? Because of this, I am finding it difficult to communicate my idea to principal engineers/ architects. How can I improve on this?



(1 comment)
  • 30
    Profile picture
    Tech Lead @ Robinhood, Meta, Course Hero
    a year ago

    First, I recommend these other career advice threads:

    Here's some other thoughts from me:

    • Look for examples - Copy-paste is one of the most powerful abilities in tech, and it applies here too. I assume there are senior/staff engineers on your team that write excellent design docs that you can easily understand. Use their docs as a template for yours. If you have questions (which you should), just ask them. If you're going to book an ad-hoc chat, you can say something like, "I'm trying to get better at writing design docs for my projects, and I really enjoy going through yours. Do you have 15-20 minutes to explain some of XYZ techniques you use - I would love to understand them and incorporate them into my doc for ABC project."
    • Just do it a lot - The cool thing about design docs is you don't need some massive, high-stakes 6-month project to do it (for those, you want to be good at writing docs by then). Anything that takes >1 month can have a small design doc, and for smaller 1-3 week tasks, you can create a super "mini" design doc in the task ticket itself or in an RFC pull request.
    • Read engineering blogs - Engineering blogs of top companies need to be very readable for maximum reach and brand impact, so they invest a lot of time making them concise and have incredible diagrams. Those are a great role model.

    I also heavily recommend going through the System Design Series I made for a real-life example of what a thorough technical design doc looks like at a Big Tech company: System Design Masterclass: Taro Playlists