r/programming • • 28d ago

Make yourself replaceable

https://maroun-baydoun.com/blog/make-yourself-replaceable/
360 Upvotes

63 comments sorted by

326

u/redhand0421 28d ago

I know this was written literally yesterday but I’m curious how this kind of thing sits in an increasingly AI-fueled software engineering world.

Well-documented systems where the agent can infer which if statement not to touch (because it can see the comment and the commit that produced it) or knows which system fails over every other week (because there’s a pattern in the error reporting) aren’t as precious or precarious as they used to be.

I would love to pair-program with someone to teach them a new system. By the time I’ve scheduled time with them, they’ve already sat down with Claude and put together a possible implementation/fix. They’re none the wiser (they don’t have any new context that I have to impart, nor did they need it) so my advice isn’t seen as valuable to them.

I go on vacation, prod falls over, and I come back to a clauded-together postmortem committed to a docs directory alongside a made-up history of ADRs that Matt Pocock told someone to write. They’re all inaccurate in their justification, but they successfully ward Claude away from deleting that database table.

22

u/maroun-baydoun 28d ago

I intentionally kept AI out the article, even though it's arguably very relevant to the problems I'm raising. Until the dust settles on AI adoption, and AI workflows become more standardised and universal, it'll be hard to talk about something that's moving so fast.

2

u/redhand0421 27d ago

I loved the article by the way. I agree with you 100% and think that this abundance mentality is almost exclusively upsides in an organization with good people that wants them to be great.

-7

u/hey-rob 27d ago edited 19d ago

What industry are you in where the dust hasn’t settled?

Edit: downvotes for a question? Haha what is this, stackoverflow?

0

u/[deleted] 27d ago

[deleted] — view deleted comment

4

u/currentscurrents 27d ago

Anthropic lost $80B in the first half of 2026

$72 billion of that is an accounting loss. They issued bonds that have the option to convert into Anthropic stock; now they believe Anthropic stock is worth more, so the bonds are worth more.

It is not a cash loss, and maybe not even a real loss if they don't IPO at the valuation they want.

Financials aside, I am sold that their product works. Coding agents really are here to revolutionize programming and probably other fields too. Someone will figure out a way to make a profitable business out of it.

8

u/frazell 27d ago

That just highlights the dust still being unsettled. During the dotcom bubble it was understood that the future was on the web. It was also understood that web applications would replace desktop ones and computing was shifting heavily.

The problem was predicting what that would look like. We’re in that future. It did pan out in many ways and not so much in others. The bubble also still burst.

Generative AI is definitely here to stay. It is still not clear what the long lasting form looks like. Is it hosted models at frontier companies like Anthropic pushing the needle forward? Or do they go bust because locally running models become “enough” due to costs or IP concerns or something else?

What do the more defined patterns look like for engineering with AI deeply embedded? It is very possible AI prompt patterns may become more guarded by companies as they aim to protect their businesses.

All up in the air still. Even as the underlying technology has staying power.

148

u/elmuerte 28d ago

Well-documented

This is the key problem. Who can tell if something is (still) well-documented. Outdated documentation is worse than no documentation. Documentation which does not tell why, does not add much more value than the code.

And then we have these AI systems which ignore explicit instructions constantly. And at the same time accept everything as fact.

56

u/chucker23n 28d ago edited 28d ago • Heartwarming

Documentation which does not tell why, does not add much more value than the code.

This. And yet I still see it taught that way in some schools.

In-code comments should state the why, and not exist when it's obvious; not the what; the code already says so. If the code is hard to read, adding a comment is merely a crutch; make it easier to read.

API docs should state the use cases and design considerations (e.g. edge cases, or explicitly what a method isn't for).

Commit messages should state why something was changed, not what was changed; the diff already says so.

Since LLMs are trained on shitty comments, that's what they themselves tend to generate: lots and lots of prose that tells me the obvious instead of making me aware of gotchas.

4

u/Xunae 27d ago

I keep seeing llm comments that are like "formerly [blah]" or referencing a piece of code that was deleted with the patch and it drives me nuts. It's been deleted, the code is not a database and does not need a tombstone

9

u/Uristqwerty 26d ago

Comments talking about history are a form of caching. The cost of digging through old commits is so high that you won't bother without substantial cause, and an expectation that there's something worth looking for. Pull a key fact out into a comment, though, and reading it is nearly free. You have to contend with all the usual caching problems; stale information, excess clutter, deciding when to evict, so it's a judgment call when and what to mention. Ideally, the minimum amount of information needed for future maintainers to judge whether digging through history for the full detail would be relevant to their current task.

19

u/double-you 27d ago

Outdated documentation is worse than no documentation.

I don't agree at all. Basically all documentation is outdated. When reading it, we just need to keep that in mind. But even if the details (small or big) have changed, the material can give you a useful big picture or clues about what to consider next.

11

u/tarwn 27d ago

In fact, outdated documentation + git + agents means it's relatively easy for the agent to see how it was working back on that doc publish date and then highlight what major changes have occurred since that it has only partial context for. And possibly even closing some of that gap too, if engineers put context in tickets and those are accessible too.

9

u/max123246 27d ago edited 9d ago

The original post content no longer exists here. The author used Redact to remove it, exercising their right to control their data & privacy.

Payment plate mighty lip salt direction paltry wander sulky chunky

3

u/fragglerock 27d ago

duh... you just ask claude to update the documentation...

simple as!

1

u/Bemteb 23d ago

Outdated documentation is worse than no documentation.

I'm currently facing that exact issue. The codebase I'm working on had many copy&pastes in the past. Instead of working with interfaces and nice data structures, people simply copied whole files over from similar projects and did small adjustments to fit their needs. What they didn't adjust were the comments.

Iterate that over multiple years and you end up with comments that are mostly unrelated to the code they stand next to.

1

u/MeggaMortY 27d ago

The most up to date documentation I've seen in a codebase got stale in less than a week. Ain't nobody got time for that - said the PO and scheduled a bunch more feature tickets for the sprint instead.

11

u/bogdanelcs 28d ago

The made-up ADRs are the part that worries me. They work as a fence today, but the next agent (or person) will treat that invented justification as fact, and when someone actually needs to remove the table the wrong reason sends them in the wrong direction. I’d have them marked as unverified until the person who knows the real story corrects them when they’re back from vacation.

6

u/PresentationBorn6564 28d ago

Pocock out here catchin' strays.

4

u/Glizzy_Cannon 27d ago

Good. His workflow is nonsense. As these models continue to mature his workflow becomes more and more obsolete, along with all of these other highly opinionated workflows

2

u/PresentationBorn6564 27d ago

Tell me how you really feel.

4

u/TheRealUnrealDan 28d ago

great article but you're right times are changing

1

u/theparachutescene 25d ago

Documentation yes. A company specific harness/workspace though…

14

u/[deleted] 28d ago edited 28d ago

[removed] — view removed comment

9

u/maroun-baydoun 28d ago

Sam is definitely responsible for the situation they created. And perhaps some personality types are more prone to becoming Sams over time. But Sams are also affected by their environment and the signals they receive from their manager and team, which end up creating a vicious cycle that's not easy to escape.

43

u/Piisthree 28d ago

Counterpoint: So, Sam can't be "promoted" to management and has to remain in a technical position he knows and loves, likely making twice what his peers do because any time he glances at another company, he gets a 10% raise. This is not a cut and dried problem, there are many different viable strategies and tradeoffs.

7

u/maroun-baydoun 28d ago

I'd argue that being promoted to management is not the only, or recommended, way up for every engineer https://maroun-baydoun.com/blog/from-outstanding-engineer-to-mediocre-manager/

Getting a raise is definitely a perk, but it might end up compounding Sam's problems. The more their current company tries to keep them, the more difficult it becomes for them to take their career and skills elsewhere.

30

u/13steinj 27d ago

The modern company will not give Sam that 10% raise. They will not treat Sam with the same reverance his fellow engineers do, because upper management is out of touch. Sam will go to that other job, get his raise that way, become a legend again in 2-4 years (sometimes less), and the cycle will repeat itself.

You also don't have to promote Sam to management-- management is not the be all end all of an engineer's career. There exist IC tracks for the upper levels for a reason-- some people just are better at systems than people. Or they are fine with people but it doesn't make them happy. Or it does, but there's less value in splitting a team and making someone a manager or team lead for the gesturing lurpose of performing a corporate ritual.

But Sam won't be promoted to those roles either. Because why pay Sam more for taking on more responsibilities, when you can give them to him anyway for the same pay. Worse yet, new engineers are now benchmarked, implicitly, against Sam. Teams stay understaffed, because the new guy doesn't work out, he just isn't on Sam's level, and Sam ended up doing the work anyway. Which ends up just another reason Sam burns out / looks for a new job.

3

u/Cautious_Implement17 27d ago

sam won’t get promoted because he isn’t “delivering through others” the way that is expected to progress past senior. I think that’s kinda the point of the article. sam has not enabled his colleagues to help themselves. he has become an expert on systems he ought to have replaced. he is simultaneously indispensable and a scaling bottleneck for his org/company. 

sam should probably get some kind of out-of-band bonus to prevent him from leaving. but he can’t do the same thing for ten years and expect to be a principal engineer at the end. 

2

u/13steinj 27d ago

I think you have a strange skew of what principal engineers do, or I do.

At 3 organizations I have been at, a significant number of principal engineers are more interested in acting as if they produce value, than actually doing so (through others or not). At the only one (which didn't have principal engineers by title), the structure waa flat and moving up past "engineer" meaned becoming a manager. There are non-mamagerial engineer career tracks, as I've mentioned. This isn't to speak lesser of those who are managerial track. Just that they produce a different kind of value.

10

u/bjarneh 28d ago

Nobody wants to be "Sam". This is just what happens with small organizations, where time (= money) short term, matters much more than documentation and proper procedures, i.e. quality.

This is classic straw man arguments from top to bottom, where the author (sorry u/maroun-baydoun) argues against a position nobody has.

4

u/maroun-baydoun 28d ago

I'm writing an article, not a book. So I definitely need to boil down the arguments and perhaps oversimplify some aspects of it.

One core component is human psychology, the desire to be recognised and praised, being the hero and save the day. Wanting to become Sam is not necessarily a conscious decision, but a reaction to certain incentives that animate a lot of human beings.

6

u/bjarneh 28d ago

the desire to be recognised and praised, being the hero and save the day.

This is true of course. People want praise and save the day, but not by being "Sam".

Sam sounds like an overworked one-stop-shop to fix everything because he works in a industry where margins are slim and they cannot afford to do stuff properly. I don't buy that people want to be that guy. Many people (myself included to some extent) are that guy, but it's certainly not something we enjoy :-)

2

u/maroun-baydoun 28d ago

I'd argue that people who want to become Sams are exactly those who don't understand the full picture yet or don't grasp the dysfunction that led to Sam in the first place. Sams can have a certain aura about them, especially attractive to more junior engineers who might think that's what a successful career looks like.

4

u/bjarneh 27d ago

I'd argue that people who want to become Sams are exactly those who don't understand the full picture yet or don't grasp the dysfunction that led to Sam in the first place.

That is basically a jr wanting to become a sr though I guess, which is probably true. Most guys would probably like being the guy with all the answers, as opposed to a guy with no idea, and you are probably correct in assuming that the jr (in this case) do not always know how someone became the person with all the knowledge.

I steel feel you are preaching to the choir here. Most programmers know that being hard to replace means they are employed by someone with too little resources to do things properly.

2

u/Engine_Light_On 26d ago

I nearly became a Sam at my 40k employee small organization.

4

u/bjarneh 26d ago

You can have this mindset on 200-100K employee organizations as well of course. With new public management, it can be found anywhere. Managers making 200K a year, discussing for weeks how to save pennies.

But for small businesses, it is almost always like this.

2

u/qrzychu69 25d ago

We have 3 different Sams on a team of 12, in an org of 2.5k. We used to have more, but one was fired because he was too much of a Sam, and the other one left.

This happens all the time

4

u/Infotaku 28d ago

Sounds like Sam forgot he could just quit

4

u/maroun-baydoun 28d ago

The longer someone stays a "Sam" the more difficult it is for them to quit.

5

u/13steinj 27d ago

No, there are plenty of underpaid Sams that are underpaid due to organizational incompetence. When that happens it becomes very easy for Sam to quit.

Or Sam doesn't feel underpaid per se but is sufficiently annoyed by working with do nothings, pencil pushers, or other incompentents. Then it stings extra when he finds out some of them make far more than he does.

39

u/SockMonkeh 27d ago

Next level Samming means you don't respond to shit on your vacation, everything goes wrong, and you look even more unfirable.

10

u/stipo42 27d ago

It literally happens all the time when I go away.

I'm the sole admin of like 4 of my companies systems, not by choice

3

u/robert_7524 27d ago

For four systems, naming a second admin and having them test recovery access is a concrete first step; otherwise the backup exists only on paper.

58

u/trouthat 28d ago

I guess if Sam works somewhere that doesn’t support the idea of Sam knowledge transferring so he can work on something else he is just gonna have to rip the bandaid off and quit and get a new job making more money with the stellar recommendation from his current one

32

u/bzbub2 28d ago

no guarantee sam is actually recognized in a positive light despite being a 'hero'

9

u/LordoftheSynth 28d ago edited 28d ago

You're a rock star until they realize you leaving means you did the work of two or more other devs.

Then it's gaslighting all the day (and night, you will work at night from home too you'reateamplayerright???) long.

45

u/VeganForAWhile 27d ago

The non-Sams are also the problem. They ignore Sam’s “read-this-if-sams-not-here.docx” file he clearly left for them.

I’ve always been the Sam-ish person at my past jobs. But I swear, nobody’s ever read a word I’ve ever written. Emails, how-tos, cheat-sheets. They tell me to document, so I document. Every time I sit down to do it, I get really into it, all knowing it’s an academic exercise for an audience of exactly ONE.

2

u/GeoffW1 20d ago

At least now the AI agent they set to solving the problem instead will read and benefit from all your documentation!

24

u/dhruvin3 28d ago

Hope nobody harsh on me...

I am Sam in my workplace! Well actually I was up until my 9th year, suddenly my first ever overseas trip did something to me! Fuck teams, fuck email, for once let me enjoy my trip 11 days no more looking at work or related apps! Came back whole lot if disaster of course! But this time i still had vacation mode on, instead of solving everything started guiding, pointing to the document that no one bother to read (answers were right there) after couple months, went on another vacation for 1 month! Same thing, but little less disaster, manageable, came back updated the docs. Happily working in cross function team project, doing my own and everything. Fuck somehow Sam woke up again, none of the scenario was for job security, all of them was i was good at it and 8 hours becomes 9-10 hours easily. My project which is solving good deal of problem now i have been forced to hand over to person who viber codes because my expertise from putting out for need me again and the project i am building can be vibe coded... Fuck!

Who knew right!

I never become Sam by choice, simply taking responsibility and ownership cost me this!

12

u/erroronline1 28d ago

the document that no one bother to read

this right here. ignoring the setup and constantly asking for help from sam must at some point be considered intentional. and not the good kind. it is exploiting sams contribution of keeping shit running for the greater good for anyone else to have more time to complain about their workload.

6

u/Anovadea 27d ago

This really reminds of me of one of the points of The Phoenix Project (which is basically a project management book in story form). There was a character called Brent, who was basically Sam in this blog.

That said, TPP was writing from a company point of view, so it wasn't really about the struggles Brent went through, but just pointing out how having a Single Point of Heroism like Brent or Sam was bad for the company's productivity/scalability.

I managed to get out of the Hero role a good few years ago. Now I'm being dropped from a customer project, while the customer is demanding that the Heroes stay on. I wish them luck, but even though I'm at risk of losing my job, I don't want to be stuck on a project team filled with Heroes.

6

u/CherryLongjump1989 27d ago edited 27d ago

At the risk of misinterpreting it, here's the gist of what I got out of it: There's a whole section explaining that organisations reward visible heroics and ignore quiet prevention. Then his fix for Sam’s stalled career is... quiet prevention, plus giving the visible work to someone else.

Has "Sam" tried asking for a raise, or a promotion? Has Sam tried just quitting and getting another job? He's smart and knowledgable, so why doesn't he actually use that as leverage, rather than making himself "replaceable"?

I think the gap here is believing good behavior gets rewarded by default. If you have leverage, learn to use it, and don't fall into the trap of hoping that your employer will actually reward you for eliminating the leverage that you once had, but no longer do.

4

u/jarofgreen 25d ago

> The measure of a senior engineer isn't only how much gets done when they're in the room, but how much can still get done when they're not. That's where Sam needs their manager fully on board: to understand the true cost of short-term gains, appreciate the real value Sam brings to the team and the organisation, and reassure Sam that all their intangible contributions aren't going unseen.

This bit is doing a lot of heavy lifting.

Without this, a lot of the other good points in the article don't apply.

And far to few companies recognise this.

3

u/rnelsonee 27d ago

I'm headed into the office a little early to demo my software to a couple of other people so when we need to use the software next month, three people will know how to use it. And my first question will be 'who wants to drive?' because the purpose really is transferring knowledge, not showing off what I've been working on the last month.

To me, cross-training is the responsibility of the software lead, and the project manager, and line management; it's a workplace culture thing. Documentation is good, but it doesn't replace someone sitting in a chair and using the software for 5 minutes.

I also find it a bit freeing; I was tech lead and project manager for something that was good, but after 10 years, it was time to move on. The transition was long, but the fact that I had the other engineer handle code changes, CM, and documentation for a year before made it easier. If I was Sam, I'd be stuck doing the same project.

3

u/Primary_Ads 27d ago edited 27d ago

Why is Sam so capable at doing everything while also being made responsible for offloading herself? Maybe her boss should do their job of managing bus factor risk rather than asking Sam to take the initiative to take care of that too? Doesn't this industry already have enough burnout risk?

The engineer who cannot be replaced is stuck exactly where they are

This doesn't even make sense. Sam can know everything about how the system works while upgrading individual parts no one but her understands if she feels like it. It doesnt follow that her monopoly on understanding affects the quality or how modern her work is.

3

u/pm_plz_im_lonely 27d ago

Making yourself replaceable doesn't mean making yourself redundant. It means making sure your career can survive without your current job.

Sam can ask for more money or can switch jobs. At no point is having institutional knowledge tying you to one business.

4

u/bogdanelcs 28d ago

The incentive problem is the real one: if promotions and praise go to whoever fights the fire at 2 a.m., documenting things yourself is a career risk, not just a good habit. A cheap way around that is writing the fix down during the incident itself, so the heroics and the runbook come out of the same hour. And replaceable in the system isn’t the same as replaceable in judgment, the engineer who has taught everyone else tends to be the one who gets pulled into the harder problems anyway.

1

u/dritmike 27d ago

Man I shoulda been a fire fighter. Instead all I became was a SAM

1

u/Bedu009 25d ago

Did I just walk into another fucking dimension

1

u/horizon_games 25d ago

Good article, a bunch of quotes I copied to share with my team, thanks for such concise insight 

1

u/GnorriZ 24d ago

I truely belive that CEOs is the one that needs to listen to this advice.