Show HN: Swimming in Tech Debt

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.

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.

>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.

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.

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.

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)

https://pages.usefulbooks.com/writing-sprint-2025

> 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"

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.

Try writing other people’s books. As in typing them into the word processor. It really helps speed things up.

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