Hey, Luca here! Welcome to the Monday 3-2-1 ✨

Every Monday I will send you an email like this with 3 short ideas about:

1. 🎽 Engineering Management

2. 🔨 Technical Strategy

3. 🎒 Hiring & Onboarding

I also send an original article every Thursday, like the last one:

• Relieving stress 🧘‍♀️

To receive all the full articles and support Refactoring, consider subscribing if you haven’t already:

Before we dive into this week’s ideas, I want to let you know about this open position by my friends at the Pi School of AI.

They are looking for a full-time AI Coach, hybrid remote and on-site, to support the activities of the School of Artificial Intelligence.

This profile will work directly with Sébastien Bratières, the school's Managing Director.

Pi School is a next-generation school located inside the startup community of Pi Campus, in Rome. I have known and worked with them for several years, and I can tell you this is a fantastic opportunity.

If this sounds like something that excites you, check out below 👇

Check the AI coach position

Now back this week’s ideas!

1) 🎽 Project vs Area docs

A lot of advice about company workspaces and docs starts with creating spaces for single functions — e.g. Engineering, Product, Marketing.

However, in healthy companies, most activity revolves around projects that span multiple areas.

So, it is useful to separate between project notes and area notes:

• 🏗️ Project notes — docs you need to deliver a project. They may span multiple areas for cross-functional teams. E.g. product requirements, designs, roll-out plan.

• 🎨 Area notes — evergreen documentation about a specific area. E.g. engineering onboarding, database schemas, company org chart.

This separation is not static in time. Project notes may move into the respective areas after the project is delivered.

E.g. a piece of the database schema for a new feature will be moved in the general database docs within the Engineering space. But if you put it there from the beginning, you are creating silos that make projects harder to deliver.

Organizing notes and docs by actionability is a good strategy that overcomes silos and focuses on outcomes.

You can checkout the PARA method by Tiago Forte — which is a popular framework about it.

More on creating good docs 👇

Refactoring

Company Docs 📖

Hey, Luca here! 👋 This is a ✨ special edition ✨ of Refactoring for free subscribers! This article was originally exclusive to paid members, but it got really popular 🔥 so I thought of opening it up to everyone. As always, if you want to receive one of these every week, consider subscribing…

Read more

a year ago · 16 likes · 3 comments · Luca Rossi

2) 🔨 Release in 10 mins

When your release time is fast, like, 10 minutes fast, good things happen:

• Devs retain a strong feedback loop, do not need to context switch and can monitor impact on production effectively.

• You are able to make multiple releases every day.

• You also make small, atomic releases, which are inherently small risk.

On the contrary, when releases take 30+ minutes, a vicious cycle happens:

• Devs start to context switch to other tasks while the release is in progress.

• Less testing and monitoring in production get done because devs lose control of when code is released.

• “Only in the morning” releases (or worse, “only beginning of the week”), instead of multiple times a day.

• Multiple features are batched and released together for convenience, which makes releases riskier, harder to debug, and it further muddies single devs’ ownership of the release.

In a nutshell: ship fast or bust!

3) 🎒 Define a career progression framework

As your company grows larger, you need consistency in the way you assess people’s skills and responsibilities. This looks trivial, but it is easy for different teams to end up with a different idea of what a Senior Engineer looks like.

Progression frameworks clarify what is expected by people in the various roles. Here is an example by CircleCI.

It can be simpler than that, of course, based on the stage of your company. Create something good enough to align stakeholders and avoid confusion.

For inspiration, check progression.fyi — a collection of frameworks from great tech companies around the world.

And that’s it for today — I wish you a great week! 🚀 If you liked the article, consider doing any of these:

1) ❤️ Share it — Refactoring lives thanks to word of mouth. Share the article with your team or with someone to whom it might be useful!

Share

2) ✉️ Subscribe to the newsletter — if you aren’t already, consider becoming a paid subscriber. That also gives you access to the community and the curated library.

p.s. 30-days money-back guarantee, no questions asked!