Blog on Refactoring English

Which Design Doc Did a Human Write?

Wed, 25 Mar 2026 00:00:00 +0000

I created three design docs for the same open-source web app:

I spent 16 hours writing one of the design docs completely by hand.
I generated one using Claude Opus 4.6 (medium effort).
I generated one using GPT-5.4 (high effort).

I generated the AI versions in a few minutes. I fed the agents a prompt that included the design docs chapter of my book and a skeleton design doc structure. The agents who wrote the AI-generated docs did not see the version I wrote.

The Most Popular Blogs of Hacker News in 2025

Fri, 02 Jan 2026 00:00:00 +0000

With 2025 wrapped up, I can finally answer a question I’m curious about every year: who were the most popular bloggers of Hacker News?

Who counts as a blogger?

I explain more in my methodology page, but it’s basically anyone who blogs as an individual rather than as part of a company or a team. For example, John Graham-Cumming blogged while he was the CTO of Cloudflare, so I count his personal blog but not his posts to the Cloudflare company blog.

What Makes the Intro to Crafting Interpreters so Good?

Wed, 19 Nov 2025 00:00:00 +0000

One of my favorite programming books is Crafting Interpreters by Bob Nystrom. It teaches you how to build a programming language from scratch. Along the way, you learn about text parsing, data structures, virtual machines, and several other skills that make you a stronger developer.

I was re-reading the book recently and realized that its introduction is delightfully effective. Developers are terrible at writing introductions, so it’s worth studying what makes the Crafting Interpreters intro so compelling.

The Software Essays that Shaped Me

Tue, 30 Sep 2025 00:00:00 +0000

I started reading software blogs before I got my first programming job 20 years ago. At this point, I’ve read thousands of blog posts and essays about software, but only a small handful stuck in my mind and changed the way I think.

“The Joel Test: 12 Steps to Better Code” by Joel Spolsky (2000)
“Parse, don’t validate” by Alexis King (2019)
“No Silver Bullet - Essence and Accident in Software Engineering” by Fred Brooks (1986)
“Choices” by Joel Spolsky (2000)
“Application compatibility layers are there for the customer, not for the program” by Raymond Chen (2010)
“Don’t Put Logic in Tests” by Erik Kuefler (2014)
“A little bit of plain Javascript can do a lot” by Julia Evans (2020)
“Choose Boring Technology” by Dan McKinley (2015)
“I’ve locked myself out of my digital life” by Terence Eden (2022)
Bonus: Brad Fitzpatrick on parsing user input (2009)

“The Joel Test: 12 Steps to Better Code” by Joel Spolsky (2000)

Joel Spolsky is the greatest software blogger of all time. His essays have informed so much of my approach to software that it was hard to pick out just one, but “The Joel Test” is my favorite.

Adam Gordon Bell on Attracting Customers through Blogging

Fri, 12 Sep 2025 00:00:00 +0000

Adam Gordon Bell is a developer, blogger, and the host of the software engineering podcast, CoRecursive. I interviewed Adam about writing and his success at attracting customers through his blog posts when he worked at Earthly.

We talk about:

How Adam consistently wrote blog posts that reached the front page of Hacker News
Discovering blog topics that attract potential customers
Techniques Adam used to strengthen his writing
The value of writing respectfully about your competitors

Transcript

Getting started with blogging
Investing outsized effort for outsized returns
Getting early feedback on blog posts
Tools for improving your writing
Finding focus for writing
Crafting blog post titles
Panel-of-experts style of blogging
Blogging respectfully about your competitor
Improving your writing through imitation

Note: I’ve lightly edited the transcript for brevity.

Reader Feedback about my Chapter List

Fri, 29 Aug 2025 00:00:00 +0000

For the past eight months, I’ve been working on my book, Refactoring English: Effective Writing for Software Developers. I’m publishing the book incrementally as I write, which means readers give me feedback about the book in real time.

I started writing the chapters I felt most confident readers would like, but now that I’m about 50% complete, I want to make sure the remaining chapters are things my readers actually want to learn.