I am sharing this in the spirit of posts like this, this, and this that give insight into what it’s like to have a popular Show HN post. Like those posts, I have stats, but I didn’t make my post very strategically, so I don’t have much advice about that. What happened to me was more accidental (as I will describe), but I have some ideas on what worked.

Timeline

On September 6th, I woke up to find that I had pre-sold 50 copies of Swimming in Tech Debt overnight. For context, at this point I had sold about 125 copies, mostly to people on my mailing list, my personal network, and through LinkedIn. That had started on August 16th with most of the sales in the first week. My daily sales were in the single digits, so the 50 was a big surprise.

My first instinct was that there was some kind of problem. But, I did a quick search and saw the Hacker News post, so I clicked it.

Even though I could see that it had a lot of upvotes and discussion, it was surprising to me because I had posted the “Show HN” four days prior. It had gotten a few votes, no comments, and had scrolled off the bottom of the Show HN front page. I had forgotten about it.

I noticed two things about this post immediately: (1) it had a new date (2) the “Show HN” had been removed from the post title. The post was still attributed to me, but I had not reposted it. I don’t know how this happened, but my post history shows two posts. The newer one eventually had the “Show HN” put back in, but not by me.

I went into the discussion and saw some good and bad feedback on the book (and also for HelpThisBook.com (HTB)—the site I was using to host the book). To be honest, my initial reaction was defensiveness on the bad feedback. But, I replied to everything in the way I would want addressed: answering questions, thanking people, and explaining my point-of-view to those with criticism.

Stats

I am not privy to all of the statistics because I don’t run HelpThisBook (HTB), which I get access to as benefit of being in the Useful Authors Group started by Rob Fitzpatrick, author of Write Useful Books. (Note: our group is running a free 6-week writing sprint starting on September 18th. Hope to see you there).

Here’s what I can see in the data I have access to:

There have been 23,000 clicks to this version of the book. I don’t have referral information, but the vast majority have to be from HN (and the various HN mirrors).

On HTB, I can see readers progressing through the book. A few people finish every day (maybe they buy, I don’t know), and several more are finding it and starting to read each day. They can highlight and give feedback, which they are doing. I used this feature a lot while developing the book (at a much smaller scale) to help make sure the book was engaging readers.

There is a huge drop-off at the first chapter. Perhaps this is due to the HTB UX (it was somewhat criticized in the HN comments). It is also undoubtedly because of the content itself (and is normal, IMO).

On the Amazon KDP site, I can see that in the first day, there were over 100 books sold, and as of now, the total since that day is almost 300, with the daily sales being more like 10-20.

My personal site statistics had a bump compared to the four weeks prior. So far, that has been sustained (but I am also sending more email).

My mailing list subscribers increased too (the tall bar is 24 new subscribers). I am sending excerpts from the next part each day, which is causing some unsubscribes, but if they don’t like the e-mail, then they definitely won’t like the book. I want to make sure that they have every chance of getting the book at $0.99 if they want it.

These are modest, but they are very meaningful to me.

What Makes a Good Show HN Post

In my experience in reading Show HN, the most important thing is having something worth showing. I hope that that’s the main reason this post did well. But, I can’t deny that something happened (either a glitch or moderator changes) that boosted this post’s chances.

I also think that early comments (good and bad) also helped it get traction. When I first went to the post, the top comment was a very funny response about writing and tech debt. There were a few very negative posts, which I engaged with respectfully. Since I had already gotten 50 sales, I knew that the book had at least resonated with some. Tech debt is a topic that people have strong feelings about—I think that drove early comments.

You can’t control any of that, but what you can do is to be ready when it does. Having something for people to do (sign up for a newsletter or buy a book) helps you make something out of the traffic than just hits to your blog. Although HTB was a great choice for gathering feedback from beta readers, if I were posting finished work, I might choose a simpler option where I would have more control over the experience and access to the stats.

What’s Next

I just made the final version of the EPUB for Amazon and set the release date to September 16th. My plan is to leave it a $0.99 for a few days as a kind of soft launch. I don’t want to raise the price until it has reviews.

Then, I will work on the print book. I hope it will be done in October. If you want to be notified of when it is ready, the best way is to sign up to my mailing list. You will also get immediate access to some of the content from Part 3 (HTB only has Parts 1 and 2).

In Tech Debt Detectors and Use Your First Commit to Fix CRAP I explained the concept of combining low code coverage with high code complexity to highlight functions that are risky to change. I mostly do this in my IDE to warn me before I change code, but it’s also useful to use it to do a global search for risky functions.

My main project is in typescript and uses jest and eslint. Here’s how I automated a search for risky functions.

Step 1: Get a list of high complexity functions

Note: by complexity, I am referring to the number of independent paths through a function, which is calculated by counting branches, loops, and boolean expressions.

Eslint has rule that allows you to set a maximum complexity. In my package.json, I call eslint via yarn this way:

"lint": "eslint \"**/*.{ts,tsx}\""

I added a line that does this but with a complexity rule

"complexity": "eslint \"**/*.{ts,tsx}\" --rule '\"complexity\": [\"warn\", 5]'"

If I run yarn complexity, I get warnings that look like this:

347:8  warning  Async function 'dbSetUserPlanBlock' has a complexity of 6. Maximum allowed is 5  complexity

I do a bunch of bash-fu and this line produces a sorted list of function names with the highest complexity.

"complexity": "eslint \"**/*.{ts,tsx}\" --rule '\"complexity\": [\"warn\", 5]'|grep Maximum |cut -d\"'\" -f2-|sort -t' ' -k6,6nr|cut -d' ' -f1,6|cut -d\"'\" -f1 "

Step 2: Find the code coverage of a function

What I need now is a way to find the coverage of a function given its name. If I run jest via yarn like this:

yarn test --coverage

it will generate a json file called coverage/coverage-final.json which has all of the coverage data. It’s a complex JSON file, but if you install jq via brew, you can use this script to see if it has coverage lower than 80% (credit: ChatGPT)

jq -r -c --arg func "$2" --argjson threshold 0.80 '
to_entries[] as $fe
| $fe.key as $file
| $fe.value as $v
| ($v.fnMap // {} | to_entries[] | select(.value.name == $func) | .value.loc) as $loc
| ($loc.start.line) as $sline
| ($loc.end.line)   as $eline
| {file:$file, name:$func, start:$sline, end:$eline} as $meta
| (reduce (( $v.statementMap // {} ) | to_entries[]
          | select(.value.start.line >= $sline and .value.end.line <= $eline)) as $s
         ({stmt_tot:0, stmt_hit:0};
          .stmt_tot += 1
          | .stmt_hit += ( ($v.s[$s.key] // 0) | tonumber | if . > 0 then 1 else 0 end ))) as $S
| (reduce (( $v.branchMap // {} ) | to_entries[]
          | select(.value.loc.start.line >= $sline and .value.loc.end.line <= $eline)) as $b
         ({br_tot:0, br_hit:0};
          .br_tot += ( ($v.b[$b.key] // []) | length )
          | .br_hit += ( ($v.b[$b.key] // []) | map( (.|tonumber) | if . > 0 then 1 else 0 end ) | add // 0 ))) as $B
| $meta + $S + $B
| .linePct    = (if .stmt_tot==0 then 0 else (.stmt_hit / .stmt_tot * 100) end)
| .branchPct  = (if .br_tot==0  then 0 else (.br_hit  / .br_tot  * 100) end)
| .overallPct = (if (.stmt_tot + .br_tot)==0 then 0 else ((.stmt_hit + .br_hit) / (.stmt_tot + .br_tot) * 100) end)
| select(.overallPct < ($threshold * 100))
| "file: \(.file)\nname: \(.name)\noverallPct: \(.overallPct)\n"
' $1

I put this in a file called is-jscoverage-pct-low, which I call like this

is-jscoverage-pct-low coverage/coverage-final.json dbSetUserPlanBlock

Step 3: Combine the two

Given a list of functions (from step 1) I can filter it based on coverage using xargs like this:

"changerisk": "eslint \"**/*.{ts,tsx}\" --rule '\"complexity\": [\"warn\", 5]'|grep Maximum |cut -d\"'\" -f2-|sort -t' ' -k6,6nr|cut -d' ' -f1,6|cut -d\"'\" -f1 | xargs -n1 is-jscoverage-pct-low coverage/coverage-final.json"

I call it like this:

yarn changerisk

And it outputs this:

file: /Users/lou/project/momentum/backend/src/db/entities/plannedBlock.service.ts
name: dbDeleteUserPlannedBlocksForTimeSpan
overallPct: 55.55555555555556

file: /Users/lou/project/momentum/backend/src/db/entities/plannedBlock.service.ts
name: dbSetUserPlannedBlocksForTimeSpan
overallPct: 62.5

file: /Users/lou/project/momentum/backend/src/db/entities/user.service.ts
name: dbSetUserSettings
overallPct: 54.54545454545454

Given a list like this, you could use it to:

1. Onboard a new developer: To fix, they need to refactor and unit-test the functions. They can likely do this without knowing much about your system. This allows them to concentrate on learning your PR processes.
2. Identify risky estimates: Anyone creating an estimate of a project that will change code should see if the files and functions they intend to change are risky.
3. Plan tech debt remediation projects: In my book, Swimming in Tech Debt, I outline a process for building and managing a tech debt backlog. You could use a list like this to build backlog items to tackle.
4. Build a dashboard: It would be nice to show the rest of the org that the number of risky functions you have is decreasing over time.