Developer marketing is show and tell

A single blog post I wrote two years ago remains the most upvoted Buttondown blog post on Hacker News.  Just use a monorepo, a 362-word post about a misadventure in splitting Buttondown into multiple git repositories then reverting back into a single repo, was enough to inspire twenty-four thousand words of comments on Hacker News.

Another blog post on my personal blog had a similar trajectory late in 2024. ‌Notes on buttondown.com, the story of buying Buttondown’s shiny new domain, got more likes on social media than almost anything else business-focused that I’d shared this year, and is right now one of the top-five most read things I’ve published on my blog.

Hacker News responded as expected. Congratulations mixed with confusion over the need for such an expenditure. Critiques on how I’d implemented the change or financed the purchase. Confusion over what Buttondown is, in the first place. Some fair, some unfounded.

But 120 upvotes and 89 comments don’t lie. Here’s what I did. Here’s how I did it. Here’s what happened after. It’s a format as old as time—and it’s the thing I’ve seen time and again become the most effective form of developer marketing.

Decisions, not dogma

Developers are builders. Makers. We’re here to change the world, at some level. We want to learn things that will help us build better, see how others did things, and one-up them in an asymptote towards the ideal software.

We’re allergic to ads. Impervious to marketing. Or so we tell ourselves.

But we like builder’s stories. We’re the types that read Folklore.org with in-the-trenches stories from Apple’s early days, the types that took apart toys to see how they worked as kids. We’re drawn like a moth to a flame when we see articles detailing other developers’ decisions and development workflows. We’ll wonder “why should I listen to you?” when we hear sales scripts, but are credulous when a developer shares how they built the thing.

There’s a rubbernecking aspect to it. Folks will absolutely tell you that you’re wrong, that there was a better way to do what you did.

But it’s the discussion that matters. People read and cared enough to comment. Any discussion is good discussion (as long as you’ve got a reasonably thick skin, and have thoughtful enough opinions to back them up in the discussion). And when hundreds of developers are reading what you’re writing and care enough to comment, that’s developer marketing.

I’m not writing about monorepos and buying .com domains as developer marketing. Yet it’s the times that I write about what I shipped and why I made the decisions I did that my writing tends to take off in developer circles.

Mindshare is marketing

There’s a reason the Twilio billboard was effective. Memorable, at least. It’s hard to imagine that billboard, specifically, convincing a CEO to walk into their office and ask a developer about Twilio. But it isn’t a stretch to imagine a developer remembering Twilio blog posts about HTTP headers and what Twilio learned implementing them for its emails, about Twilio’s open-source video conferencing apps, or about building a burner phone with Twilio or SQLite versus PostgreSQL and the process their blog team went through in picking a database. All popular Twilio posts on Hacker News, none directly trying to sell you on using Twilio (except perhaps the burner phone post). Yet each article reinforced the concept that here’s a technical team building unique things in interesting ways. And when you need to add phone API to your app, or your boss takes Twilio’s billboard up on its question, you’ll think hey, they seem like a good service to use for this project.

Here’s what we built. Here’s what we’re going to build. Here’s what we or someone else built with our product. By default, you'll probably give those posts more attention than anything fueled by SEO research or trending topics. And bit by bit, the dev platform builds mindshare. One day, you too might decide to use it.

Some of the best guides on the internet aren’t written for others; they’re written for the writer. I did this, I went down this rabbit trail and came back to regret the misadventure, here’s how I finally slayed the dragon. Because one day, I’m going to stand at that same fork in the road, and either my having written it down will keep the details fresh in my memory, or the written record becomes instructions that past me left for future me. “I’m not writing it down to remember it later, I’m writing it down to remember it now,” as the quote inside every Field Notes notebook reads.

Search engines love such writing, because there’s a fair chance you were not the only one to encounter your exact dilemma (so there are people searching for this thing) but you may have been the only one to solve it in that unique way (so your guide is truly unique). Readers love it, devs anyhow, because they love seeing how others built stuff, even if only to see if they could have done better. And those articles are the most fun to write. They’re a great postmortem, a log for what I was thinking at the time, and a way to put a line in the sand and say here’s my opinion, here’s what I’m building, and why.

You know you’ve won when people mention your developer-focused writing, years later. Stripe’s Online migrations at scale guide—written after doing a “large migration of our hundreds of millions of Subscriptions objects”—was still living rent-free in someone’s mind, five years after publication, when it was the first thing referenced in a Hacker News discussion of favorite technical blog posts this year. A guide to migration is one thing. A guide written from the trenches after migrating one of the largest online services? That’s another thing entirely, worth referencing years later. Unlikely to have directly turned into Stripe signups, but absolutely likely to have been one of many factors in developers choosing Stripe when spinning up a new project.

Tell people what you’ll do, what you did, and what happened.

There’s an old script for giving a speech: Tell them what you’ll tell them. Tell them. Then tell them what you told them. You absolutely shouldn’t follow that exactly, unless you want a boring speech, but the general framework applies. Maybe you open with a story that hints at what you’re going to tell them. Then you expound on the point, and wrap up with something that drives it home.

That same script works for planning what you’re going to write about on your developer newsletter. Tell them what you’re going to do. People love knowing what’s coming next, enough that it’s worth playing chicken with the Osborne effect sometimes. Then tell them what you did, how you built it, why you made the architectural and language and framework choices you did. Then tell them what happened, how people used it—or better yet, how you use that thing yourself, Twilio-burner-phone-tutorial style.

It’s the clear-eyed view of having built the thing and made the decision that people love.

Opinionated takes get traction. Clearly state a decision you made—any decision, ever—and you’ll get affirmation and pushback. Someone will have chosen the same, and be glad to have confirmation they made a good choice. Someone else will have chosen a different path, a perfectly fine, logical move, for their circumstances and the moment in time when they made that decision, and they’ll push back. Maybe they’ve even noticed something you didn’t, and you’ll realize they have a point.

That’s fine. Part of having skin in the game. Your declaration will get people talking. Sharing. Remembering, if you’re lucky. You’ll learn along the way. And one day, one post at a time, they’ll warm to the idea of what you’ve built. Maybe they’ll want to build on it too. And that’s when you’ve won.