Hey, Luca here, welcome to a weekly edition of the💡 Monday Ideas 💡 from Refactoring! To access all our articles, library, and community, subscribe to the full version:
Resources: 🏛️ Library • 💬 Community • 🎙️ Podcast • ❓ About
1) 📑 The AI Docs Paradox
Is AI going to make docs less or more important? To me, it depends on what docs.
Let’s bucket docs into three macro categories:
The “Why” docs — they record why we built things the way we did. What are the goals, the constraints, the assumptions, and the principles we build on top of.
The “What” docs — they record what has been built. What features, what system design, what workflows.
The “How” docs — they record how stuff has been built, and how it works. It’s the implementation details, the runbooks, the code comments, and so on.
AI is especially useful on the How — we can argue on the quality of AI-generated code, but it is pretty obvious by now that AI documents code better than humans.
The Why is and will stay a domain of humans for a long time. It’s where you translate business context into tech decisions, and it’s vital to write this down. It’s also the part that no one, AI or human, can figure out by simply looking at a codebase: it’s additional context that is separate from the software itself.
The What is trickier and I guess it’s the real frontier where humans and AI are going to collaborate. Starting from good whys, AI can draft good whats in terms of design docs, system architectures, and even roadmaps.
So, this pyramid structure reveals why AI is both making docs less and more important simultaneously:
📉 Less important — the massive bottom layer of "how" documentation — implementation details, code comments, API references — can increasingly be generated on-demand.
📈 More important — the slim top layer of "why" documentation — business context, decisions, constraints — becomes critical because it's what AI needs to generate everything else.
This is somewhat counterintuitive because many teams have this exactly backwards. We spend 80% of our effort on the how, which is more extensive, more volatile, but also easier to generate for AI, and 20% on the why, which only we can provide instead.
So how do you flip this ratio? We published a full guide on this just recently 👇
2) 🗳️ Answer our survey about AI and win $150!
As you may have seen, we are working on a big industry report about how engineers and teams use AI at work, and how they feel about it.
We need your help to figure this out! 👇
Your answers will shape our findings and the best insights will be quoted in the final report.
We are also giving away 20 paid memberships for free ($150 each!) 🎁 to people who answer the survey! We will draw the winners next month as soon as the survey closes.
3) 🪴 Coaching vs Mentoring
Recently I interviewed Joel Chippindale on our podcast. Joel is an experienced CTO Coach and coach-in-residence in the Refactoring Community.
During our chat, he made an important distinction between mentoring and coaching – two approaches that are often confused but fundamentally different in philosophy and execution.
📚 Mentoring — is about learning from someone with different experiences than yours, leveraging their knowledge to accelerate your learning.
📣 Coaching — instead starts with the assumption that you're already capable and resourceful. The idea is that most of the answers to your challenges are already in your head somewhere: they just need help getting out.
As a coach, Joel says he creates thinking partnerships to help CTOs get clearer about themselves and their situations. He challenges their (self-limiting) beliefs, and helps them examine available options for change, but without providing directive guidance.
Here is the full interview with Joel:
You can also find it on 🎧 Spotify and 📬 Substack.
4) ⏳ Consider the payoff timeline of abstractions
We often warn against creating premature abstractions because these may be invalidated by quick product evolution. Something that stands true today might not be true tomorrow, so we should only invest, engineering-wise, in what feels core to your product.
In my experience, though, this is not enough to guarantee that an abstraction is successful. The other angle you should consider is the timeline for its payoff.
You may invest in the right abstraction, but whose payoff is too far in the future, and that still leads to failure. You may be accounting for 10x the traffic, or 10x the engineers, and you don't live enough to see it.
So, 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 1) truly core to your value prop, and 2) whose payoff is reasonably short-term.
We discussed this in a great chat a couple of years ago with Andrew Twyman, former Staff Engineer at Dropbox 👇
And that’s it for today! If you are finding this newsletter valuable, consider doing any of these:
1) 🔒 Subscribe to the full version — if you aren’t already, consider becoming a paid subscriber. 1700+ engineers and managers have joined already! Learn more about the benefits of the paid plan here.
2) 📣 Advertise with us — we are always looking for great products that we can recommend to our readers. If you are interested in reaching an audience of tech executives, decision-makers, and engineers, you may want to advertise with us 👇
If you have any comments or feedback, just respond to this email!
I wish you a great week! ☀️
Luca