In software development, we collect anti-patterns to recognize common traits that lead to poor outcomes in our software. I thought it would be helpful to do the same for software blogging, so I’ve catalogued the most frequent mistakes I see from beginner bloggers. The meandering intro Preamble still counts as meandering “The reader knows everything I know except this one thing” Overreliance on lin

The first time I saw Michelangelo’s David in person, I wept. Never in my life have I witnessed a more beautiful piece of content. I wasn’t the only one who felt that way. Museum patrons all around me were looking up from their phones to admire David as well. Despite it being legacy content, David was so scrollstoppingly captivating that it generated stronger engagement than TikTok and Instagram co

A good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation. It’s also the best way to coordinate design decisions among teammates and partner teams. I’ve written design docs as a developer at Google, Microsoft, and within my own companies . The specifics vary, but the underlying pr

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 w

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” lik

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 the about 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 b

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 terr

You’ve spent weeks carefully writing a design document for your software project, but what happens next? How can you get useful feedback from your teammates? How do you prevent your design review from devolving into petty arguments? 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

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 Engin

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 u

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 thing

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

A release announcement should showcase how the user’s experience today is better than it was yesterday. That sounds obvious, but most release announcements forget that there’s a user at all. The announcements just enumerate new features without ever connecting them to real user workflows. The announcement essentially becomes a changelog with better writing. For example, here’s a “changelog” style

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

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, but there are several techniques I’ve found to be useful from personal experience. A

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 Start Does this sentence contain passive voice? Passive 😴 Active ⚡ Next Question Accuracy: 0 %

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 Start Does this sentence contain passive voice? Passive 😴 Active ⚡ Next Question Accuracy: 0 %

Your high school English teachers probably warned you that passive voice is dangerous and forbidden. Outside of school, people probably tell you that passive voice is fine, and your high school teachers were just being pedantic. I think your high school English teachers were right and that developers should almost always avoid the passive voice. Wait, what’s passive voice? In English, sentences ca

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 foll