Show HN: Swimming in Tech Debt
78 comments
·September 5, 2025bee_rider
You think it is the first half. You’ll realize later on that really you need a totally different structure to write the book. You’ll try to refactor the whole thing, but some obstinate subset of the original readers will insist on using the original index. In the interest of backwards compatibility, you’ll jam the new structure into the margins (so they can keep their precious index).
It’s text-debt.
Cthulhu_
Top tier comment, lol. This is the reality though, be it text, code, or design; you work hard on it, you're happy with the results, show it to others, and think it's almost done. But the 20/80 rule applies in multiple ways. You think you're at 80%, but in reality you're only at 20%. Or the last 20% will take 80% of your time.
Real life example, we were presented with a redesign of a website with an undertone of "this is it, I have worked hard on it, I am happy with how it turned out". But then we, the pesky software developers, get in and start asking questions. "Where's the mobile design? 60% of visitors visit the site through mobile but you started with a desktop design?", "What if the user increases their font size, as per the legally mandated WCAG 1.4.4 rule?", "Did you consider dark mode?" "How does this work with a touch device?" "How does this work with a screen reader?", "What about this and this and this use case?". It goes on.
tibbar
I think a big difference between being a professional and a beginner is, a beginner will work very hard on the most obvious part of the problem. And might get something reasonable after a while. But the professional knows that the obvious part isn't where most of the difficulties lie, they'll probably use some tool to handle the obvious part near automatically, and they'll factor in all these invisible requirements into their original estimate.
loumf
I started writing the book in Obsidian, but realized I needed something a little better. So, I took it to Scrivener, which is where the first draft was completely developed (it can maintain references and a TOC somewhat).
But once I needed editors, it had to be in Word and all of the references needed to be rebuilt when that was completed. It's now in a contractor's hands, using some book making software (not even sure which, I think an Adobe product).
So, yeah.
jampa
As someone who is also writing a book (for the first time), I hate how accurate this is.
I wrote my first draft in 3 months, about 200 pages... Six months later, I haven't delivered a quarter of the book. And I will probably revisit those delivered chapters later.
loumf
If you are interested, my writing group is doing a free, 6-week (1-hour on Thursday) accountability group sprint. We spend most of the time writing (quick chat at the beginning and end)
pryelluw
Try writing other people’s books. As in typing them into the word processor. It really helps speed things up.
jcelerier
> You’ll try to refactor the whole thing, but some obstinate subset of the original readers will insist on using the original index
and as always the answer is simple: "use the old version of the book or bite the bullet"
MomsAVoxell
>In the interest of backwards compatibility, you’ll jam the new structure into the margins (so they can keep their precious index).
Its fine, they just need to tweak the workflow and wire up some kanban.
xnx
This is why I never make any drafts that I might have to change later. I always think of the entire book ahead of time without and type it out exactly without errors. /s
brudgers
Congratulations on writing a book and getting it out in the world.
1. It took me two tries to realize there is more than the table of contents and find the Unlabeled links on the left. Just make the text in the TOC clickable.
2. Maybe text navigation didn't work the first time because I did not select the correct option on the popup about interaction. This is a distraction from reading irrespective of what I picked.
3. Advice: make the reading experience work like readers expect. There are conventions. Trying to be clever doesn't benefit your readers...and will annoy at least one of them.
4. Nobody likes popups. Nobody. Nobody.
Good luck.
zachrip
This is a website to get feedback about their book, your ux complaints are with "helpthisbook."
brudgers
The author is looking at this page.
The author chose the format to present their work and posted the link. They own the problems associated with their book, are in a position to choose other options, and can benefit from the feedback.
The website designers probably aren't looking at this page and even if they were, the problem is not as important to them as it is to the author.
loumf
Agreed. I am pretty sure that they are going to look at it though. I am in close contact with them.
conartist6
The swimming analogy is not a strong start. You disavow an obvious and strong analogy to monetary debt right away while dumping us into this strange metaphor that depends on us having an intuition for how you think and feel about swimming, and specifically swimming laps? Instead of setting the stakes high right off the bat you've lowered them and lost my attention with this wandering train of thought that has no clear relationship to the topic you wish to discuss...
conartist6
I'm reading a bit more now and you're realizing that your debts are real and cost something all the time so that you will have to pay them. Nothing about swimming explains why this might be, though monetary debt sure does.
loumf
The analogy I am going for is the water resistance. The debt payment is the burst of momentum you get from pushing off the wall.
I think of tech debt as something you are dealing with all of the time and something inevitable.
I don't like the financial analogy because it implies that you "took out a loan" by taking a short-cut, and that you are obligated to pay it. There is definitely some of that, but mostly, I see it as good decisions that didn't age well. And also, that you may be ok with living with it.
conartist6
The fungible nature of money helps explain why that is the case. One dollar bill is as good as another, something people know from handling cash. Paying down a debt is one kind of investment. Maybe it costs you $100/day to service that debt. If someone offers you a chance to invest that same money that you could have used to pay off the first debt and by investing earn divdends of $200/day, then the fact that one dollar is as good as another is what means that you should do it.
But even then you're also not (yet) getting to the heart of it: what is the value of tech debt? You still make it sounds like a damp rag dragging on you rather than an integral part of an energetic strategy. Money also gives people a clear analogy for why sometimes you want debt -- why and how it can be used as a tool.
In the swimming analogy I would say incurring a debt is like creating a wall that you can burst off of, at the cost of increasing the resistance of the water. Yeah it's a weird analogy. To be more literal, debt buys you the time you need to figure out the optimal direction and especially the critical priorities that will reward work -- will reward investment. It buys time to learn the requirements from experience, and for people to come to some community consensus as to which needs are most imminent. But only if the person managing the debt thinks of it as a tool to be used in this manner.
conartist6
You go right back to the monetary analogy when you need to explain that focusing on debt created value.
The thing that I think the swimming analogy doesn't capture well is that the resistance of water is fixed. The walls of the pool will be there to push off of no matter what you do. These are the intuitions you're asking people to draw on and they don't map.
4ndrewl
Isn't that same resistance the thing that enables you to float in the first place though? I don't really swim so don't understand the analogy I'm afraid.
The debt analogy works because you're taking a shortcut that allows you to eg get to market sooner (Vs perhaps not at all).
d0mine
Monetary debt is often a useful tool. Technical debt in many cases is just shortsightedness in throwing delayed time bombs around. It is built on the hope that you won't need to return on this minefield again (the product dies sooner).
mikestorrent
This is a good insight. The real gambles behind tech debt are not taken on the same way a company would take on real debt. If there is analysis of it, and it's not just a sneaky shortcut by a dev (either being lazy or working to a deadline), then it's not considered in terms of future cash flow or any other kind of meaningful metrics that matter over time. It only comes due if you want it to; you only pay interest on it when you interact with it. Sometimes it really is Good Enough for the slapdash thing you're working on. Sometimes more crap on top of more crap is just how the thing you're working on goes, and trying to fix it is tilting at windmills... especially if it's just to make your employer rich by mildly improving efficiency on their ad delivery platform.
loumf
Thanks for the feedback. The reason that I put up half the book and offered it for $1 to start was to make sure that people that didn't like it wouldn't buy it.
I struggled with this opening and it definitely could have been better.
conartist6
Sorry, I'm a notoriously harsh critic. That probably comes from being homeschooled by two English major parents (a poet-professor and a journalist).
loumf
No worries at all. I really do appreciate constructive feedback. I put every draft of the book out there that I could, and this is my best version of making the book I wanted to make that resonated with at least some people.
I totally get that it's not for everyone.
natch
Someone has to mention Working Effectively With Legacy Code, by Michael Feathers, still a fantastic book.
https://www.amazon.com/Working-Effectively-Legacy-Michael-Fe...
loumf
Love that book. Also, "A Philosophy of Software Design" by John Ousterhout
willahmad
First of all, congratulations
Honest question expecting your honest response. How much of it's written by AI? Recently, I noticed I am liking thoughts of real people over the super structured, emdash-y, zero grammar mistake AI texts.
I want to support authors who share their experiences, rather than guiding AI to write thoughts
loumf
I did not use AI to write this. I paid professional editors to help me get it polished. There were 4 rounds with 5 different people. I also got lots of grammar/typo comments using helpthisbook (hundreds of readers pointing out errors).
I did (very rarely) take single sentences to ChatGPT and ask it for the correct way to punctuate it.
I personally have always used em-dashes, perhaps incorrectly. I actually tried to learn the correct usage and stick to using it when appropriate. One of my goals in writing this book was to become a better writer, which I could only do (IMO) by writing and getting editors to help me.
natch2
I don’t have time to write a more detailed review just yet, but given all the highly critical comments, I just wanted to put out there that I read quite a bit of this last night and thoroughly enjoyed it!
loumf
Thanks! I put up half the book so that only people that liked it would buy it. I am ok with it not being for everyone. I got about 70 sales overnight, so I am totally fine with some negative comments as well. Most are constructive.
I am a little miffed that someone called it AI slop. I wrote every word (with professional editors helping). So, that hurts a little :)
sublinear
The chapter titles are too long, and the contents of each are too anecdotal.
That means I can't find an interesting chapter, and just blindly picking one leaves me with a stream of consciousness to sort through.
I don't get the sense that this is coherent enough to be the book or guide people expect. It really does feel like a collection of loose blog posts. That's not necessarily a bad thing if you change how this is presented.
If you want to tell stories that's fine, but don't then organize this as if each chapter is a lesson. That's misleading because there's not enough conceptual meat on the bones there. Organize the chapters by the stories you want to tell, not by the concepts you hope the reader sees in them.
Distilling and organizing the knowledge you think you have in your blog posts would mean an entire rewrite of this book and more careful analysis than just labeling each as its own chapter and adding a few sentences to fill gaps. The book people want would probably be 10% narrative and 90% instructional. This is 100% narrative in its current form.
null
mdaniel
I'd recommend resubmitting as Show HN since this is your product and those submissions actually have their own dedicated URL. Plus, the way the title reads now is as if the submission was a blog you found
loumf
I did submit as ShowHN. I don’t know how and when this got edited.
dugmartin
I haven't read the book but I've known Lou for probably 20 years and he is a very smart, very pragmatic software engineer who also happens to be a great guy. I look forward to when this is launched so I can buy a copy.
loumf
Thanks! You can buy it now for a buck. But, if you are waiting for print, that will be about a month later.
giulianob
I read the first part and I enjoyed it. I agree that us developers aren't great at communicating tech debt effectively. Managers are also not great at prioritizing it. I think the "debt" analogy has been a net negative as management often thinks "we'll just pay it later" but don't often see how much pain it's causing. So having a resource to help both sides on this topic is very valuable.
loumf
Thanks. That’s my belief as well. I would have loved to come up with a better term.
In the next two parts of the book I try to convince managers to give some autonomous time to engineers to do whatever tech debt projects they think is best. With some constraints and accountability.
withinrafael
Thank you for writing down and sharing your experiences and insights, and making it accessible for just a mere buck.
loumf
No problem. I hope you find some useful tips in it.
This is the first half of my book, “Swimming in Tech Debt”. It is available at a pre-launch sale price of $0.99 (https://loufranco.com/tech-debt-book).
I have been working on it since January 2024. It is based on some posts in my blog, but expands on my ideas quite a bit.
In September 2024, excerpts appeared in Gergely Orosz’s Pragmatic Engineer newsletter, which helped me get a lot of feedback that expanded the book from my initial idea. This half is about what I expected to do before that —- the rest of the book goes into team and CTO practices.