Show HN: Swimming in Tech Debt
99 loumf 60 9/5/2025, 5:33:03 AM helpthisbook.com ↗
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.
https://www.amazon.com/Working-Effectively-Legacy-Michael-Fe...
It’s text-debt.
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.
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.
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.
https://pages.usefulbooks.com/writing-sprint-2025
and as always the answer is simple: "use the old version of the book or bite the bullet"
Its fine, they just need to tweak the workflow and wire up some kanban.
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.
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.
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.
There are parts of the debt analogy that (I think) really hurt getting it dealt with. I think that explaining it like that to non-engineering decision makers will make them think they understand it and then quash projects based on some kind of ROI analysis of debt payments. They'll be happy to have the debt.
I don't see "swimming" replacing it anytime soon -- and the energy you'd expend trying to shift the metaphor might be better spent elsewhere.
That said, "swimming in debt" still works, as a fairly common and intuitive metaphor. Break-even is treading water, profitability is flying above the waves, and accruing debt can put you in Davy Jones' locker.
The debt analogy works because you're taking a shortcut that allows you to eg get to market sooner (Vs perhaps not at all).
I struggled with this opening and it definitely could have been better.
I totally get that it's not for everyone.
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.
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.
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
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.
I am a little miffed that someone called it AI slop. I wrote every word (with professional editors helping). So, that hurts a little :)
Which is all true but the concept of making deliberate trade offs for speed and expedience invariably gets lost.
Stories about ongoing improvement - tech enhancement - just get seen as more positive. Plus that term covers both remediating original shortcut choices as well as new engineering improvements arising.
I once wrote a book (about 400 pages, after editing). No one read it, and rightly so. It covered a topic in a preachy, dictatorial manner. It’s long buried in a deep, unmarked grave, in the desert.
It was accurate, well-written, well-structured, relevant, and useful, but assumed a tone that was pure poison. It was aimed at an audience that did not respond well to the tone.
It was extremely valuable education for me, though. My mother was a scientific editor, and edited the book. It was brutal, and quite humbling, but her work ensured that the book was absolutely perfect. I don’t think I’ve ever shipped anything as close to [unpopular] perfection as that book.
Even though I have never been particularly interested in writing book-length stuff, since then, I continue writing to this day[0]. Here’s the latest thing I did (released a few days ago)[1]. I don’t really write for others; I write for myself.
Good luck.
[0] https://littlegreenviper.com/miscellany/
[1] https://littlegreenviper.com/series/passkeys/
[EDITED TO ADD] I typically get some downvotes, when I link to my postings. Long ago, I favorited a comment that I made, explaining this[2]. I don’t expect anyone to actually read it before hitting the down arrow, but I figured that I’d add it here, for elucidation.
[2] https://news.ycombinator.com/item?id=31860143
I also mostly write for myself, but I want to get more of it out there because I think it's useful.
I didn't know helpthisbook existed. Interesting service.
As you may have noticed, people are conflating the HTB stuff with your material, and HTB should keep that in mind.
I have found that talking about improving software Quality is a deeply unpopular topic, on HN, and that kinda breaks my heart.
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.
No comments yet
You seem to be writing about other concepts and just redefining them as tech debt.
I left more detail in comments, but if I had purchased this book I would be seeking a refund, because I would be expecting a detailed exploration of technical debt, not just a focus on bad coding practice.
I really don't want people to buy it if they won't like it.
Very distinct babblezone liturgy.
I get that you might not like my writing, but it is mine.