newsletter.param.codes

Share this post

Write a design document

newsletter.param.codes

Write a design document

Param Singh
Sep 18, 2020
1
Share this post

Write a design document

newsletter.param.codes

I read this blog post and spent some time thinking about how writing skills have helped me become a better engineer so far (and how they could help in the future!).

My first job was at a place where ALL communication happens in a public IRC channel. This basically meant that you need to be good at written communication to be able to have meaningful impact. So I understood the need to be able to write well implicitly very early. However, I didn’t really explicitly think of these benefits until I started working for Stripe which has a pretty big writing culture.

Here’s what I got: It is generally a good idea to write a design doc before starting a project. No matter how small the project is, if you think it’ll take you longer than a week, spend a few hours writing a design document. Try to list out the work that you’ll need to do. Think of how you’ll release the changes. Think of people who’d be interested in looking at your work and get those people to review it.

Why write words instead of code? There are a number of advantages:

  • Writing a design document down to the nitty gritty details helps you figure everything out yourself. I worked on a lot of projects willy nilly, without much planning and I can see now how good planning early on would have helped me execute on these projects better.

  • Writing a design document allows coworkers (or other opinionated people) to communicate their opinions to you early. That way, you can resolve disagreements and (more importantly) get better ideas early on, making it much much easier to execute. It’s not fun rewriting an entire pull request because code review brought up significant issues or because code review revealed a much easier way to do what you want to do.

  • Writing a design document keeps you honest. Once you have a design document fleshed out, you know what tasks you need to finish. If you’re the kind who puts deadlines or milestones into design docs, maybe you even know the dates when you should finish such stuff.

  • It helps you become better at estimating work. One of the skills that I’ve been trying to develop is being able to make realistic estimates on how long a project would take. It’s harder than it looks, I have a tendency of being overly optimistic, or just missing things that will need to be done. When you’re writing a story of how you’d finish a project, you’re made to go through ALL the things that you need to do, and making better estimates is easier.

Also, the future is remote and asynchronous, it’s probably best to brush up on those writing skills, they’re gonna be good skills to have when your teammates work in a completely different time zone.

Share this post

Write a design document

newsletter.param.codes
Previous
Next
Comments
TopNewCommunity

No posts

Ready for more?

© 2023 Param Singh
Privacy ∙ Terms ∙ Collection notice
Start WritingGet the app
Substack is the home for great writing