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.

Why Improve Your Writing?

Tue, 03 Mar 2026 00:00:00 +0000

I’ve worked as a developer for 20 years, and I’ve always cared about clear writing. When I join a new team, the first thing I do is ask to update the onboarding documents. As I ramp up on the team, I document what I learn and encourage my teammates to do the same.

Sometimes, other developers ask me why I invest so much into writing. Programming is technical, so why spend time on a “soft skill” like writing? Isn’t that why we have technical writers and product managers?

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.

How to Get Meaningful Feedback on Your Design Document

Mon, 03 Nov 2025 00:00:00 +0000

You’ve spent weeks carefully writing a design document for your software project, but what happens next? How can you get useful feedback about it from your teammates? How do you prevent your design review from dragging on for months?

I’ve been through many design reviews in my career as both the author and reviewer, and I have a special fondness for effective reviews. Through trial and error, I’ve learned techniques that help the review process move smoothly and yield material improvements to the design.

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.

Underused Techniques for Effective Emails

Wed, 16 Jul 2025 00:00:00 +0000

For software developers, there’s tremendous value in writing effective emails. Good emails save time, reduce misunderstandings, and earn you recognition within your company.

How to Write Compelling Software Release Announcements

Wed, 25 Jun 2025 00:00:00 +0000

A release announcement showcases how the user’s experience is better today than it was yesterday. That sounds obvious, but most release announcements seem to forget that there’s a user at all.

So many release announcements just enumerate new features in a way that’s totallly divorced from how real people use the software. The announcement is essentially just a changelog with better writing.

For example, here’s a “changelog” style of announcing a new feature:

How to Write Blog Posts that Developers Read

Thu, 27 Mar 2025 00:00:00 +0000

I recently spoke to a developer who tried blogging but gave up because nobody was reading his posts. I checked out his blog, and it was immediately obvious why he didn’t have any readers.

The developer had interesting insights, but he made so many mistakes in presenting his ideas that he was driving everyone away. The tragedy was that these errors were easy to fix. Once you learn to recognize them, they feel obvious, but some bloggers make these mistakes for years.

HN Popularity Contest

Thu, 13 Mar 2025 00:00:00 +0000

What counts as a personal blog?

I count a site as a personal blog if:
- the site contains written content (not just an app or a video)
- the site is authored by a single person
A blog still counts as a personal blog even if the blogger is a professional journalist (e.g., Brian Krebs) or blogging on their company’s website (e.g., Raymond Chen).
Social media (Twitter / Mastodon) doesn’t count as a personal blog.
Podcasts websites count as blogs if they’re hosted by a single person and are independently owned.
I exclude github.com links even though some people post blogs there.
- It’s too hard to filter out all the non-blog links to github.com.
- Pages under the github.io domain are eligible.

Aggregating scores

I aggregate scores across all submissions that received a score of at least 20 and are not dead or deleted.
- e.g., If a single link was submitted 100 times and never scored at least 20, none of those submissions would increase the aggregate score for the domain.
Duplicate submissions of the same URL all count as long as each submission received at least 20 points.
I aggregate together domains when the author moved domains as long as the new domain is the canonical URL for the old content.
- e.g., all submissions from christine.website count towards xeiaso.net, their new canonical URL.
I do not aggregate together blogs by the same author at different domains if they contain distinct content.
- e.g., kalzumeus.com and bitsaboutmoney.com count separately, even though Patrick McKenzie is the author of both.
To reduce the size of the dataset, I only include domains that have accumulated at least 500 points across all submissions.

Update frequency

The data automatically updates on the second day of each month, but I sometimes do out of band updates.

How to Write Useful Commit Messages

Fri, 07 Mar 2025 00:00:00 +0000

Effective commit messages simplify the code review process and aid long-term code maintenance. Unfortunately, commit messages don’t get much respect, so the world is littered with useless messages like Fix bug or Update UI.

There’s no widespread agreement about what makes a good commit message or why it’s useful, so I’m sharing my thoughts based on my 20 years of experience as a software developer.

An example of a useful commit message
What’s the point of a commit message?
Organizing information in a commit message
- Put the most important information first
- Use headings to structure long commit messages
What should the commit message include?
What should the commit description leave out?
Further reading

An example of a useful commit message

Here’s an example of a useful, effective commit message:

Can You Spot the Passive Voice?

Fri, 31 Jan 2025 00:00:00 +0000

This exercise tests your ability to recognize the passive voice in the context of developing software.

For each sentence, click:

Active ⚡ if the sentence has no passive voice (active voice only)
Passive 😴 if the sentence contains passive voice

Can You Spot the Passive Voice?

Fri, 31 Jan 2025 00:00:00 +0000

This exercise tests your ability to recognize the passive voice in the context of developing software.

For each sentence, click:

Active ⚡ if the sentence has no passive voice (active voice only)
Passive 😴 if the sentence contains passive voice

Passive Voice Considered Harmful

Fri, 31 Jan 2025 00:00:00 +0000

Your high school English teachers probably warned you that passive voice is dangerous and forbidden. Then, when you were an adult, some guy in a leather jacket told you that passive voice is cool and should be used whenever it’s desired.

Well, the tide has turned again. If you’re a software developer, stop using the passive voice.

Wait, what’s passive voice?

In English, sentences can have one of two structures: passive voice or active voice.

Rules for Writing Software Tutorials

Thu, 02 Jan 2025 00:00:00 +0000

Most software tutorials are tragically flawed.

Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. Other times, the author brings in hidden assumptions that don’t match their readers’ expectations.

The good news is that it’s easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules.

Rules

Write for beginners
Promise a clear outcome in the title
Explain the goal in the introduction
Show the end result
Make code snippets copy/pasteable
Use long versions of command-line flags
Separate user-defined values from reusable logic
Use unambiguous example values
Spare the reader from mindless tasks
Keep your code in a working state
Teach one thing
Don’t try to look pretty
Minimize dependencies
Specify filenames clearly
Use consistent, descriptive headings
Demonstrate that your solution works
Link to a complete example

Write for beginners

The most common mistake tutorials make is explaining beginner-level concepts using expert-level terminology.

Refactoring English

Which Design Doc Did a Human Write?

Why Improve Your Writing?

The Most Popular Blogs of Hacker News in 2025

What Makes the Intro to *Crafting Interpreters* so Good?

How to Get Meaningful Feedback on Your Design Document

The Software Essays that Shaped Me

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

Adam Gordon Bell on Attracting Customers through Blogging

Transcript

Reader Feedback about my Chapter List

Underused Techniques for Effective Emails

How to Write Compelling Software Release Announcements

How to Write Blog Posts that Developers Read

HN Popularity Contest

What counts as a personal blog?

Aggregating scores

Update frequency

How to Write Useful Commit Messages

An example of a useful commit message

Can You Spot the Passive Voice?

Can You Spot the Passive Voice?

Passive Voice Considered Harmful

Wait, what’s passive voice?

Rules for Writing Software Tutorials

Rules

Write for beginners

What Makes the Intro to Crafting Interpreters so Good?