How to Write Blog Posts that Developers Read

by Michael Lynch, published

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.

I know because I’m one of them.

I’ve been blogging about software development for nine years. My best posts have reached 300k+ readers, but many of them flopped, especially in my first few years.

Over time, I’ve learned techniques that help some blog posts succeed and the pitfalls that cause others to languish in obscurity.

Why listen to me?🔗

I’m going to say a bunch of gloaty things to establish credibility, but it feels gross, so let’s just get it out of the way:

  • I’ve written a software blog for nine years, and it attracts 300k-500k unique readers per year.
  • My posts have reached the front page of Hacker News over 30 times, many of them reaching the #1 spot.
  • I launched a successful indie business by writing a popular blog post about my product.
  • My articles frequently appear on reddit and Lobsters.

My software blog receives 300k-500k unique readers per year.

I don’t claim to be the world’s best software blogger, but I’ve had enough success and experience to share some useful lessons.

Get to the point🔗

The biggest mistake software bloggers make is meandering.

Often, the author has some valuable insight to share, but they squander their first seven paragraphs on the history of functional programming and a trip they took to Bell Labs in 1973. By the time they get to the part that’s actually interesting, everyone has long since closed the browser tab.

Internet attention spans are short. If you dawdle before making your point, the reader will seek out one of the literally billions of other articles they could be reading instead.

So, how do you convince the reader to stay and continue reading your blog post?

When the reader arrives, they’re trying to answer two questions as quickly as possible:

  1. Did the author write this article for someone like me?
  2. How will I benefit from reading it?

Give yourself the title plus your first three sentences to answer both questions. If you find yourself in paragraph two and you haven’t answered either question, you’re in trouble.

To show the reader you’re writing for them, mention topics they care about, and use terminology they recognize. If you throw out jargon or unfamiliar concepts, the reader assumes the article isn’t meant for them and clicks away.

Your introduction should also make it clear to the reader how the article will benefit them. There are many possible benefits you can offer:

  • A technique the reader can apply in their work or personal life.
  • A clear explanation of a concept that impacts the reader’s work or personal life.
  • An insight that gives the reader a better understanding of a particular technology or industry.
  • An interesting story that resonates with the reader.

Example: “if got, want: A Simple Way to Write Better Go Tests”🔗

I recently wrote an article about improving tests when using the Go programming language.

Here’s the title and first paragraph:

if got, want: A Simple Way to Write Better Go Tests

There’s an excellent Go testing pattern that too few people know. I can teach it to you in 30 seconds.

This article immediately answers the two questions:

  • Did the author write the article for someone like me?
    • The article is for Go developers.
  • What’s the benefit of reading it?
    • You’ll learn a new testing technique in 30 seconds.

Think one degree bigger🔗

When you write an article, you hopefully have a type of reader in mind. For example, if you wrote an article called “Debugging Memory Leaks in Java,” you probably assumed that the reader is an intermediate to advanced Java developer.

Most software bloggers never think to ask, “Is there a wider audience for this topic?”

For example, “intermediate to advanced Java developers” are a subset of “Java developers,” who are a subset of “programmers,” who are a subset of “people who read blog posts.”

Categories and subcategories

If you wrote an article for intermediate and advanced Java developers, how much would have to change for the article to appeal to Java developers of any experience level?

Often, the change is just an extra sentence or two early in the article to introduce a concept or replace jargon with more accessible terms.

Jeff: Sony has a futuristic sci-fi movie they’re looking to make.

Nick: Cigarettes in space?

Jeff: It’s the final frontier, Nick.

Nick: But wouldn’t they blow up in an all-oxygen environment?

Jeff: Probably. But it’s an easy fix. One line of dialogue. “Thank God we invented the… you know, whatever device.”

Thank You for Smoking (2005)

The set of all Java developers is about 10x larger than the set of intermediate and advanced Java developers. That means small tweaks can expand the reach of your article by an order of magnitude.

Obviously, you can’t broaden every article, and you can’t keep broadening your audience forever. No matter how well you explain background concepts, your tax accountant will never read an article about memory leaks in Java. The point isn’t to write articles that appeal to every possible reader but to notice opportunities to reach a larger audience.

Example: “How I Stole Your Siacoin”🔗

One of my earliest successes in blogging was an article called “How I Stole Your Siacoin.” It was about a time I stole a reddit user’s cryptocurrency (for noble reasons, I promise).

Initially, I thought the story would resonate with the few hundred people who followed a niche cryptocurrency called Siacoin. As I was editing the article, I realized that you didn’t have to know anything about Siacoin to understand my story. I revised it slightly so it would make sense to cryptocurrency enthusiasts who had never heard of Siacoin.

Then, I realized I could even explain this story to people who knew nothing about cryptocurrency. I adjusted the terminology to use regular-person terms like “wallet” and “passphrase” and avoided crypto-specific terms like “blockchain” or “Merkle tree.”

The article was my first ever hit. It became the most popular story of all time not only on the /r/siacoin subreddit but also on the larger /r/cryptocurrency subreddit. It reached the front page of Hacker News, even though readers there are generally hostile to cryptocurrency-focused stories.

Siacoin subcategories

“How I Stole Your Siacoin” only needed a few tweaks to be enjoyable for people who didn’t know anything about cryptocurrency.

Plan the route to your readers🔗

Suppose you wrote the greatest beginner’s tutorial imaginable for the Python programming language. Both your five-year-old nephew and 80-year-old dentist blazed through it with ease and delight. Everyone who reads your tutorial goes on to become a Python core contributor.

Bad news: nobody will ever read your Python tutorial.

“Lies!” you shout. “Thousands of developers learn Python every year. Why wouldn’t my objectively awesome tutorial become popular?”

Well, think it through. What happens after you hit publish? How does anyone find your article?

You’re probably thinking: Google.

Yes, your friend Google will index your tutorial and use its secret Google magic to identify your article’s superior quality. Before you know it, your tutorial will be the top result for python tutorial.

Except that can’t happen because there are so many Python tutorials out there already on sites that Google prefers over yours. You’ll never even make it to the first page of results.

It’s nearly impossible for a new blog post to rank well in Google for the search term python tutorial.

Okay, so you’ll submit your Python tutorial to reddit. The /r/python subreddit has over 1.3 million subscribers. If even 5% of them read your article, that’s a huge audience:

The /r/python subreddit has over 1.3 million subscribers.

Whoops! /r/python only accepts text posts, not external links, so you can’t post your tutorial there.

The /r/python subreddit disables the option to submit external links.

Fine, then you’ll submit it to Hacker News. They accept anything and let their members decide what’s interesting. Surely, they’ll recognize the quality of your work!

Nope, it will flop there, too. Hacker News doesn’t like tutorials, especially for mainstream technologies like Python.

You can try sharing your tutorial by tweeting it, skeeting it, or tooting it, but unless you already have a massive following on social media, that won’t reach a critical mass either.

So, what’s the answer? How do you get people to read your amazing Python tutorial?

The answer is that you don’t write a beginner’s Python tutorial.

You need a realistic path to your readers🔗

If you want people to read your blog, choose topics that have a clear path to your readers. Before you begin writing, think through how readers will find your post.

Questions to ask when considering an article topic

  • Is it realistic for readers to find you via Google search?
    • Are there already 500 articles about the same topic from more established websites?
    • What keywords would your target reader search? Try searching those keywords, and see whether there are already relevant results from well-known domains.
  • If you’re going to submit it to a link aggregator like Hacker News or Lobsters, how often do posts like yours succeed there?
  • If you’re going to share it on a subreddit or niche forum, does it have any chance there?
    • Does the forum accept links to blog posts?
      • The bigger the community, the stricter the rules tend to be about external links and self-promotion.
    • Do blog posts like yours ever succeed there?
    • Is the community still active?

The best plan is to give your post multiple chances to succeed. If you’re betting everything on Google bubbling your post to the top, it could take months or years for you to find out if you succeeded. If you’re relying on Hacker News or reddit to tell you whether your article is worth reading, they’re going to break your heart a lot.

Example: “Using Zig to Unit Test a C Application”🔗

In 2023, I wrote an article called “Using Zig to Unit Test a C Application.” It was about using a new low-level language called Zig to write tests for legacy C code.

Before I wrote the article, I knew that there were several places where I could share it. By luck, they all worked out:

Show more pictures🔗

The biggest bang-for-your-buck change you can make to a blog post is adding pictures.

If your article features long stretches of text, think about whether there’s any photo, screenshot, graph, or diagram that could make the post more visually interesting.

  • If you’re talking about a program with a graphical interface, show screenshots.
  • If you’re talking about an improvement in metrics like app performance or active users, show graphs.
  • If you’re writing about your server getting overloaded, show a screenshot of what that looked like in your dashboard or email alerts.
  • If you’re explaining a difficult concept, draw a diagram.

I hire illustrators for most of my posts (including this one). I typically pay $50-100 per illustration. For simple diagrams like the nested circle sketches above, I use Excalidraw, which is free and open-source.

You can also use free stock photos and AI-generated images, as they’re better than nothing, but they’re worse than anything else, including terrible MS Paint drawings.

Even a terrible MS Paint drawing is more interesting than an AI-generated image.

Accommodate skimmers🔗

Many readers skim an article first to decide if it’s worth reading. Dazzle those readers during the skim.

If the reader only saw your headings and images, would it pique their interest?

The worst thing for a skimmer to see is a wall of text: long paragraphs with no images or headings to break them up. Just text, text, text all the way down.

Tool: Read like a skimmer🔗

Here’s a JavaScript bookmarklet that you can use to see what your article looks like with just headings and images.

Drag the link to your browser bookmark bar, and then click it to see what your article looks like to skimmers.

Example: Boring structure vs. interesting structure🔗

I wrote my article, “End-to-End Testing Web Apps: The Painless Way,” in 2019, before I thought about structure.

If you skim the article, does it make you want to read the full version?

Probably not. The headings don’t reveal much about the content, and the visuals are confusing.

Consider my more recent article, “I Regret My $46k Website Redesign.”

If you skim that article, you still see the bones of a good story, and there are interesting visual elements to draw the reader in.

One of those articles barely attracted any readers, and the other became one of the most popular articles I ever published, attracting 150k unique readers in its first week. Can you guess which is which?

“Not Quite How Developers Read” illustration by Piotr Letachowicz. Steve Jobs illustration by Loraine Yow.