Taro Logo

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

Profile picture
Mid-Level Software Engineer [62] at Microsoft2 years 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
    2 years 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

Microsoft is an American technology corporation which produces computer software, consumer electronics, and personal computers. It developed the Windows line of operating systems, the Microsoft Office suite, and the Internet Explorer and Edge web browsers. Microsoft is often credited for ushering in the modern PC era.
Microsoft42 questions