My general takes (as someone who also has a somewhat popular blog) is that
The inverted pyramid is almost always the correct format for your text. I often put the tweet-length version of the post in the title or first paragraph. Get to the point quickly, then elaborate. Means you can bail out at any point of the text and still take home most of what mattered, while the meticulous crowd can have their nitpicks addressed toward the end.
The problem of finding an audience is best solved by being really transparent about what you're about. Inverted pyramid solves that. There's no point to drawing in people who aren't going to be interested. Retaining existing readers beats capturing new readers.
I'm less bullish on images, unless they are profoundly relevant to the text. Illustrations for the sake of having illustrations are no bueno in my opinion. You want to reduce distractions and visual noise. Images should above all never be funny.
Counterpoint: writing blog posts so that they are read by someone else completely defeats the point of writing for 99% of people. I do not mean to say that this the advice in the post is bad advice, just that if you focus on being read (i.e., checking rankings on HN, only writing articles that don't exist yet) you probably just will just stop writing at one point, because most of the stuff on the web just isn't read, and writing just to be read is probably not very motivating.
Writing, even if no one reads what you write, is super valuable, and fun! Writing something down is to structure your own thoughts so that you learn more about the topic and about yourself. In my experience, publishing a piece of your writing just ensures that you double check your thinking, but most of the benefit is learning more about what you intend to write about.
So here's my advice: just write posts on what you think is interesting on your personal blog. Don't install analytics, just write it down, publish it, and put it on your LinkedIn. Someone will see it someday and will like it.
I reckon if you wanted to choose just a single rule it should be, "Write something that you yourself would actually read." The problem is that our brains are designed to sort of lie to us and tell us that what we've created is amazing when in fact we'd never actually read it if someone else had written it. If you can find a way to be objective and see your own writing as the far-from-perfect mess it actually is.
(In principle, you could use "write something that someone else would actually read", but I think this is much harder, because it's much harder to know how other people would react! If you yourself would read it, well, we aren't that unique, lots of other people would read it too.)
Steve Ballmer never diversified his Microsoft stock like Bill Gates did. But it made him an immensely rich guy—currently richer than Gates himself. Now, does that mean picking a company and going all in is a good idea? Probably not.
I’m all about improving my writing to be useful to others. However, diversifying my content to attract a broader audience usually results in the most vapid, formulaic, clickbaity articles. No matter how many eyeballs they get, I don’t get any pleasure reading or writing them. And writing is how I slow down and shape my thinking. I like doing it for myself, not for the audience. But I deeply appreciate however many readers I get.
Hacker News has a pattern of articles it favors: Zig, Rust, why Go isn’t for the “smart” developers, arcane PL theories, nostalgia about some Lisp variant, why you should blog, small internet, and so on. Ninety percent of the time, they’re forgettable. I usually learn more from the comments than the articles themselves. I also don’t want to write just to capture a certain kind of audience.
I mostly write about things I’m currently working with or interested in. I tend to write something I think past me would find useful—and future me might, too. That’s very different from shaping your writeups for the audience. My stats aren’t impressive as the author, but I do get a few thousand monthly visitors to my blog[1]. I’ve had job offers because a recruiter came across one of my posts somewhere. It’s a different way of thinking about writing, but I’m immensely happy with the result.
So long as your article has a decent enough structure – which this article makes it seem is the only thing that matters – I reckon there are two ways to make blog posts that developers read and share;
1. make so many of them, you'll repeatedly hit gold eventually
2. go the extra yard with research and/or effort
The intro's "The developer had interesting insights" makes it sound like they failed blog was full of opinion pieces. Very few opinion pieces succeed, but they're the easiest to write (i.e. the first category). It might work for some people, but for us unknowns, nobody really cares. Go the extra yard and make it interesting by doing a deep dive of the subject.
I've fully focussed on the second approach. As a consequence, each article takes a lot of time to complete, so I generally don't finish more than one per month. I try to make them all something I can actually be proud of (which is quite a challenge), and then I spend a lot of time tweaking the structure, making things less verbose, and improving scanability – I rely on making sentences bold a lot for that. I try to use relevant images, but I find actually helpful ones are hard to make for developer content. While hiring illustrators is a good idea, I doubt many writers are willing to pay for that.
To make my articles more interesting, I try to make a custom component for each article to spice it up and slowly grow the component library I have available for my blog. It doesn't always work though – for my last article I spent several hours building an easter egg that only 22 people (<0.1%) interacted with it.
TBH as someone with a lot of experience in this (I plan to write more when I get to 69 posts on the front page of hacker news, I'm only at 55 right now), about half of it is that you have to be personally jazzed about the post. If you're not, it'll show and the audience here will eat you alive and either flag you or mock you. You gotta sink or swim.
You gave a strong example of the stick figures working better than generic AI art. Ironically, the AI image was necessary to drive home the point. That AI stock “photo” is just plain boring, even in contrast to stick figures on a plain white background. Those two images are worth an infinity of words that most anti-AI art people would rant about human creativity or whatever.
>Even a terrible MS Paint drawing is more interesting than an AI-generated image
True and factual. I don't get why people don't just take pictures from Flickr, CC BY-SA, just post it and link the author. Having an AI-generated image in your writing makes me think the whole text is also AI-generated.
By the way, the best thing you can do for skimmers is include images, because they break the flow of text. You can also try using headings that stand out for having inverted colors for example, but people generally don't do that with markdown and generic heading CSS.
Appreciated the reminder to show, not tell with images and structure. Most dev blogs are just walls of text with the occasional code block. Adding even rough diagrams or skimmable headings makes a massive difference.
Ironically I skimmed the first few paragraphs and the essence to attracting attention is to "get to the point". At which point I scrolled down to the bottom just reading the headlines and just couldn't be arsed. I'm usually more interested in the comments.
A meta question one should ask is: why do you want to write a technical blog in the first place? If it is fame and fortune, blogging about your favorite obscure technology probably isn’t the easiest path.
On the other hand, if it is for the purpose of your own understanding, then it doesn’t matter whether you have enough pictures, or your first paragraph elicits sufficient dopamine to compete with TikTok. By default the most important audience will be yourself in the future, and by definition if you’re rereading the article you’re already interested. Instead, you should focus on highly detailed and precise language which help you understand the topic in the future.
Likewise, if it is for the purpose of bolstering your professional profile, it’s unlikely your content will be evaluated on how catchy it is.
> 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.
It's funny because I've found that my posts do better on HN without any headings (though I do use shorter paragraphs for the no-headers).
p.s. almost all of my front-page posts were no-headers!
Yes, but also if you are not good in writing articles don’t quit writing them, getting better in writing articles comes with.. writing articles.
Also you should not necessarily optimize your blog post for the max amount of readers, that’s only useful in commercial cases or when you want to commercialize yourself.
I'm really curious how these insights might apply to other internet media (mediums?). Similar principles at play for YouTube videos? Audio-only podcasts? I'm only halfway through the post but really excited to think of how this might extrapolate to other formats.
I agree with the author.
What’s recently worked for me is to ask the AI to critique my blog/hn/reddit posts and ask it to be brutally honest.
The feedback that I got from it was eye opening and I used to write exactly like the author mentioned: a lot of meandering.
Promise progress payoff.
Give users a promise about what you're going to show them, make constant progress, and have a nice payoff at the end.
Brandon Sanderson talks about it in his lecture series on youtube.
Honestly, thanks... I'm about to start my first foray into blog-post writing, and I have a couple specific topics in mind. I had been debating whether I should start with the "background and motivation" section, or if I should just get to the point. Your article helped me decide that I should definitely just get to the point first. If the reader cares to go deeper into my specific motivation, then they can. But at the end of the day, the purpose of my post is to share knowledge - and soapboxing should be secondary.
I recently opined here that devs should really stop setting their blogs in monospaced fonts, and got downvoted to -4, which is very funny.
It’s TRUE!
Monospaced fonts are a thing for two reasons:
1. Historically, they were all computers did, because it is simpler to have fixed widths. (Remember Knuth's biggest contribution was typesetting -- it is complex). Do you know why the Macintosh changed this? Because Jobs was inspired by a calligraphy course he audited at college
2. Because lining up text is important for programming
Other than that, variable-width text is much easier to scan and read. Yes, even for people who spend a lot of time working with code.
You should also be setting a maximum line-width of about 40em, as it becomes hard to read text when the eye has so far to travel back to the left side.
You also shouldn't center paragraphs 99% of the time, because it’s better when your eye can 'seek' to a consistent left edge (assuming LTR languages!)
If you want to know more, please look it up or ask the nearest LLM!
This advice strikes me as very sensible if I want to maximize my audience of readers who lack the attention span to take in any information of real depth.
How to write blog posts that developers read
(refactoringenglish.com)592 points by rbanffy 28 March 2025 | 153 comments
Comments
The inverted pyramid is almost always the correct format for your text. I often put the tweet-length version of the post in the title or first paragraph. Get to the point quickly, then elaborate. Means you can bail out at any point of the text and still take home most of what mattered, while the meticulous crowd can have their nitpicks addressed toward the end.
The problem of finding an audience is best solved by being really transparent about what you're about. Inverted pyramid solves that. There's no point to drawing in people who aren't going to be interested. Retaining existing readers beats capturing new readers.
I'm less bullish on images, unless they are profoundly relevant to the text. Illustrations for the sake of having illustrations are no bueno in my opinion. You want to reduce distractions and visual noise. Images should above all never be funny.
Writing, even if no one reads what you write, is super valuable, and fun! Writing something down is to structure your own thoughts so that you learn more about the topic and about yourself. In my experience, publishing a piece of your writing just ensures that you double check your thinking, but most of the benefit is learning more about what you intend to write about.
So here's my advice: just write posts on what you think is interesting on your personal blog. Don't install analytics, just write it down, publish it, and put it on your LinkedIn. Someone will see it someday and will like it.
(In principle, you could use "write something that someone else would actually read", but I think this is much harder, because it's much harder to know how other people would react! If you yourself would read it, well, we aren't that unique, lots of other people would read it too.)
Also, props for this stark picture of reality: https://refactoringenglish.com/chapters/write-blog-posts-dev...
I’m all about improving my writing to be useful to others. However, diversifying my content to attract a broader audience usually results in the most vapid, formulaic, clickbaity articles. No matter how many eyeballs they get, I don’t get any pleasure reading or writing them. And writing is how I slow down and shape my thinking. I like doing it for myself, not for the audience. But I deeply appreciate however many readers I get.
Hacker News has a pattern of articles it favors: Zig, Rust, why Go isn’t for the “smart” developers, arcane PL theories, nostalgia about some Lisp variant, why you should blog, small internet, and so on. Ninety percent of the time, they’re forgettable. I usually learn more from the comments than the articles themselves. I also don’t want to write just to capture a certain kind of audience.
I mostly write about things I’m currently working with or interested in. I tend to write something I think past me would find useful—and future me might, too. That’s very different from shaping your writeups for the audience. My stats aren’t impressive as the author, but I do get a few thousand monthly visitors to my blog[1]. I’ve had job offers because a recruiter came across one of my posts somewhere. It’s a different way of thinking about writing, but I’m immensely happy with the result.
[1]: https://rednafi.com/
edit: I think I read HN comments more than HN articles. Interesting
1. make so many of them, you'll repeatedly hit gold eventually
2. go the extra yard with research and/or effort
The intro's "The developer had interesting insights" makes it sound like they failed blog was full of opinion pieces. Very few opinion pieces succeed, but they're the easiest to write (i.e. the first category). It might work for some people, but for us unknowns, nobody really cares. Go the extra yard and make it interesting by doing a deep dive of the subject.
I've fully focussed on the second approach. As a consequence, each article takes a lot of time to complete, so I generally don't finish more than one per month. I try to make them all something I can actually be proud of (which is quite a challenge), and then I spend a lot of time tweaking the structure, making things less verbose, and improving scanability – I rely on making sentences bold a lot for that. I try to use relevant images, but I find actually helpful ones are hard to make for developer content. While hiring illustrators is a good idea, I doubt many writers are willing to pay for that.
To make my articles more interesting, I try to make a custom component for each article to spice it up and slowly grow the component library I have available for my blog. It doesn't always work though – for my last article I spent several hours building an easter egg that only 22 people (<0.1%) interacted with it.
True and factual. I don't get why people don't just take pictures from Flickr, CC BY-SA, just post it and link the author. Having an AI-generated image in your writing makes me think the whole text is also AI-generated.
By the way, the best thing you can do for skimmers is include images, because they break the flow of text. You can also try using headings that stand out for having inverted colors for example, but people generally don't do that with markdown and generic heading CSS.
Still, for most people who are still finding their style and (for some reason) are optimizing for popularity, this seems like sound advice.
I loved your course from a few years ago - "Hit the Front Page of Hacker News".
The biggest takeaways from that course were to write for beginners, and assume no prior knowledge/context.
I've often been fascinated by articles featured on HN, that were totally out of my field, but somehow didn't make me feel stupid.
A few concepts from your course gave me some very refreshing "aha!" moments. Since then I'm almost never staring at a blank page.
Thanks so much, and looking forward to the book!
Edit: looks like I'm not alone.
I'm happy to take any feedback or answer any questions about this post.
On the other hand, if it is for the purpose of your own understanding, then it doesn’t matter whether you have enough pictures, or your first paragraph elicits sufficient dopamine to compete with TikTok. By default the most important audience will be yourself in the future, and by definition if you’re rereading the article you’re already interested. Instead, you should focus on highly detailed and precise language which help you understand the topic in the future.
Likewise, if it is for the purpose of bolstering your professional profile, it’s unlikely your content will be evaluated on how catchy it is.
It's funny because I've found that my posts do better on HN without any headings (though I do use shorter paragraphs for the no-headers).
p.s. almost all of my front-page posts were no-headers!
this is one of the lessons of The first minute, a short book that goes well with this blog post.
Also you should not necessarily optimize your blog post for the max amount of readers, that’s only useful in commercial cases or when you want to commercialize yourself.
This! But how to overcome it? Some times to better convey the idea you have to write a lot.
Split the article in parts? Only provide a very high level overview?
And how long can be a blog post or article until people start to get bored and leave?
It’s TRUE!
Monospaced fonts are a thing for two reasons:
1. Historically, they were all computers did, because it is simpler to have fixed widths. (Remember Knuth's biggest contribution was typesetting -- it is complex). Do you know why the Macintosh changed this? Because Jobs was inspired by a calligraphy course he audited at college
2. Because lining up text is important for programming
Other than that, variable-width text is much easier to scan and read. Yes, even for people who spend a lot of time working with code.
You should also be setting a maximum line-width of about 40em, as it becomes hard to read text when the eye has so far to travel back to the left side.
You also shouldn't center paragraphs 99% of the time, because it’s better when your eye can 'seek' to a consistent left edge (assuming LTR languages!)
If you want to know more, please look it up or ask the nearest LLM!
You could always pay Google.
The real litmus test :)