Continuous docs, product engineers, good abstractions 💡

Monday Ideas — Edition #66

Hey, Luca here! Welcome to the Monday Ideas 💡

Every Monday I will send you an email like this with 3 short ideas about making great software, working with humans, and personal growth.

You will also receive a long-form, original article on Thursday, like the last one:

The Four Types of Work 🗂

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

p.s. you can learn more about the benefits of the paid plan here.

---

---

</> Coderpad

Have you ever had to reverse-sort a binary tree at your job? Probably not.

That’s why 4,000+ engineering teams (including Netflix, Lyft and Spotify) have ditched the algorithm interview questions and use CoderPad’s collaborative IDE to actually code with candidates (See the Sandbox) 👇

With a realistic and customizable IDE that supports 40+ languages and frameworks, you can drag and drop a repo, add packages with npm install & watch code playback after the interview.

It’s a great way to pair program with candidates to see if they would be a good fit for your team.

Coderpad is a sponsor of Refactoring 🙏 check out here how we run sponsorships transparently.

---

1) 📑 Continuous Docs

I have found that teams that are good at writing docs, all have a major thing in common: they don’t write docs only at the end of a project — they write them throughout its whole life cycle.

In fact, writing docs — of whatever kind — has many benefits:

1. 💭 Help your reasoning — writing is thinking. Going through the process of writing a formal document helps solidify your reasoning and come up with a better solution.

2. ⚡ Improve output — you can support your writing with previously created templates, checklists, and examples. These make the work lighter and lead to better results.

3. 💬 Improve communication — it is easier to have good conversations about complex topics when these are backed by writing. You get more thorough reasoning and easier convergence.

4. 📔 Future reference — docs naturally record decisions and can be used for posterity.

These benefits happen throughout the whole life of a project, from inception to release to future maintenance.

Now, I have found that most teams over-index on the future reference use case, while neglecting the first two. But writing docs only after the fact is like retrofitting unit tests to production code: not completely useless, but you miss out on a lot of value.

Also, writing docs at the end is genuinely harder than doing it gradually while the work is in progress. Artifacts like meeting notes and design docs are not only useful per se — they naturally turn into long-term docs, later, with very little effort.

So the best way to write more docs — and write better ones — is usually to find ways to write them throughout the whole project lifecycle.

You can find more ideas about writing good docs in this recent Refactoring guide 👇

How to Write Documentation 📑

---

2) Abstractions should be core + have short payoff

When talking with early stage startups, I warn them against heavy engineering investments and premature abstractions, for two reasons:

1. 📈 Product evolution — product evolution often invalidates your assumptions, turning your formerly sensible abstractions into big piles of tech debt.

2. 🔭 Distant payoff — you may invest in the right abstraction, but whose payoff is too far in the future, and don't live enough to see it.

With time and gray hair I have become more and more conservative about tech investments.

As a startup I would focus on stuff that is truly core to your value prop, and whose payoff is reasonably short-term.

---

3) ✨ The Rise of Product Engineers

In recent years, I have noticed that more and more engineering roles are being identified by their area of impact (e.g. Product Engineer, Customer Success Engineer), rather than tech platform (e.g. Frontend Engineer, Backend Engineer)

Out of these, the Product Engineer role is the most representative of this shift and has become a staple in successful companies like Stripe, Intercom, Atlassian, and more.

Here is how Intercom defines it:

As a PE, you’ll be taking ownership of real customer problems by building smart, efficient solutions to both backend and frontend [...] There are projects for you to own in multiple areas, such as our messenger, bots, rule matching, [...]

The push for Product Engineers fits a broader trend in making product / tech roles wider and giving people more ownership and autonomy.

To me, the Engineers vs Product Engineers feud resembles the one between Product Owners and Product Managers.

• Product Owners have mostly tactical responsibilities. They groom the backlog, write user stories, prioritize what to do next, and attend all the Agile meetings. Their focus is short to mid-term.

• Product Managers have more strategic responsibilities. There is overlap with Product Owners about how they both shape what to do next, but PMs are also responsible for the product vision and success. Their focus is mid to long-term.

A traditional Agile model

In PM-based teams, there is the opportunity for engineers to step in and take on some of the PO’s duties that the PM is not going to cover.

In high-performing teams, PMs provide direction and support but most often leave Engineers in charge of creating tickets and managing actual tasks. Requirements focus on outcomes, rather than how to explicitly build stuff, leaving engineers free to make decisions that matter.

The PM + PE model. As the PM scope “shifts to the left”, engineers fill in the gap.

This culture promotes more ownership and enables personal growth.

You can find real-world stories about how product engineering works in companies in this previous article 👇

Product Engineers ✨

---

✖️ Trinetix

Have an innovative product vision or transformation idea?

In case you missed it, last week we promoted the great work done by Trinetix, which makes you move from ideation to value creation in 5 simple steps.

Power your strategy and de-risk innovation via rapid validation, actionable user insights, and strategic experience transformation — securing long-term value for your business, employees, and customers.

---

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

1) ✉️ Subscribe to the newsletter — if you aren’t already, consider becoming a paid subscriber. You can 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