If you are not a subscriber of Interesting Data Gigs, join 5125 Data geeks (between this newsletter here, its Substack copy, and LinkedIn) that receive it directly in their inbox each week — it’s free.

Want to advertise here? Apply here

Why you should document everything, not only your code

Hey Data Geek.

Today I wanted to share the best tip that has helped not only to grow exponentially in my career, but at the same I’ve helped tens of people to become better engineers.

The tip is very simple but very powerful at the same time: When I finish an interesting problem at work, I document everything I did, not only the code.

Sometimes: the document is more important than the code because it could help the next person to understand the context of the solution.

In Data Engineering, this is critical because we work with several sources at the same time, we build a Data Model to answer a business problem, we choose one particular stack to solve that problem; and very often, we need to explain to a new engineer in his/her onboarding process why we did what we did.

A good document explaining all this in the same codebase is the perfect place to put all this.

Writing is a skill you develop with time, and it’s the same as coding: you need to practice, practice, practice and you will improve it with time. It’s not only about the length of the specs or papers we write, but the clarity of your writing which from my perspective is more important.

I am sure that if you write consistently, especially some docs that help your peers or coworkers to do a better job, you will get promoted in the process, especially if those docs help them to be more productive or make their job faster and with better quality.

This is called “Writing for impact”.

There are many companies where writing is part of the culture. My favorite examples are Stripe, Amazon, Sourcegraph, Gitlab, Ashby, Ramp, Uber, Shopify, and many more.

Here are some of my favorite resources to become a better writer: