Write a design document

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.