Migrations, skip-level 1:1s, and Notion vs GDocs💡

Monday Ideas — Edition #107

🔌 Speakeasy – unlock API integrations

This week I am happy to promote Speakeasy, lets you easily create SDKs for your API.

Speakeasy provides idiomatic, type-safe libraries with retries and pagination — it’s the DevEx your API deserves.

---

1) 🔨 How Intercom dodged a painful migration

A few weeks ago we interviewed Charity Majors, CTO at Honeycomb.

During the interview, Charity shared a great story of how good observability enabled a team to make the right technical decision, taking the business context into account.

A few years ago, Intercom had to do a giant database migration because they had outgrown the largest EC2 instance size.

They thought it was going to take a year or so. Big deal. So they integrated Honeycomb and started instrumenting their code with app and user IDs.

At some point, one of the engineers was just poking around, breaking down and grouping events and figured out that something like 75 to 80% of the execution time for that database was being taken up by one user ID who was paying ~$20 a month.

So, instead of the full sharding migration they could just throttle that guy, and figure out things later. This story seems extreme but it shows how technical decisions are inseparable from business decisions, and how good observability helps with that.

You can find the full interview below 👇

Observability & Testing in Production — with Charity Majors 🎙️

---

2) 📑 Notion vs Google Docs

Many companies don't get the difference between using Office/GDocs and Notion (or Coda, etc.) for their internal documents.

Many think these tools are just about "nice formatting and emojis" (real quote from a friend of mine).

Is it really so?

For decades, companies have created documents that fell under a few, rigid categories: spreadsheets, text, presentations. We have done so with Microsoft Office and we do the same, more recently, with Google Docs.

These tools propose a model of the world where you create every time a specific, single document for a purpose. Everything you need should be in that document, with little connection with the others.

This model was inspired by real, paper documents. You write and share them with people, physically, each on its own.

In recent times, new tools rose to propose a different approach. Notion, Coda, and the likes, focus more on the relationships between documents than documents themselves. They help us create a body of knowledge that is dynamic and connected.

While Microsoft Office was inspired by paper documents, these tools are inspired by Wikipedia.

In other words, while the old generation of tools is *skeumorphic* and mimics reality, the new one is, finally, internet-native.

This brings benefits both to companies and individuals:

• For individuals — it changes how we can learn new things and connect them to our existing knowledge. It allows us to create second brains for ourselves.

• For companies — it changes the way people work together. Information is not siloed anymore, you connect different pieces of information to generate insights and improve collaboration.

I wrote a full guide about creating good company (and tech) docs, which you can find below 👇

How to Write Documentation 📑

---

3) 🔀 Boundaries in skip-level 1:1s

If you are introducing skip levels for the first time, be prepared for people to be confused about them. Both your reports (managers), and reports of your reports.

In both cases, you want to tell them exactly why you are having those.

Especially to managers, you should clarify that you are not going to overstep your boundaries and take away ownership from them. Skip levels are 90% about feedback, while most of the action stays on the manager’s side.

So, as the one holding skip level 1:1s, how should you act on items that come up in conversation?

It may seem weird, but 80% of the time the best answer to anything you hear is "have you talked about this to your manager?"

What follows is most often useful, and you want to learn more about it before you take any action. A “yes” may imply the manager didn’t act on this (why?), while a “no” may hint at some communication/interpersonal problem.

The trickiest part of skip levels is being helpful—so that meetings feel valuable and the report keeps coming with good ideas/feedback—while not stepping onto the managers’ toes.

It is kind of an art, even more than with regular 1:1s.

More ideas about how to have good skip level 1:1s 👇

Skip Level 1:1s 🔀

And that’s it for today! If you are finding this newsletter valuable, consider doing any of these:

1) 🔒 Subscribe to the paid version — if you aren’t already, consider becoming a paid subscriber. 1500+ engineers and managers have joined already! Learn more about the benefits of the paid plan here.

2) 🍻 Read with your friends — Refactoring lives thanks to word of mouth. Share the article with your with someone who would like it, and get a free membership through the new referral program.

I wish you a great week! ☀️

Luca