zlacker

How to write blog posts that developers read

submitted by rbanff+(OP) on 2025-03-28 11:01:19 | 603 points 154 comments
[view article] [source] [go to bottom]

NOTE: showing posts with links only show all posts
◧◩◪
6. jasode+kt[view] [source] [discussion] 2025-03-28 14:14:41
>>sunk1s+rr
> In what sense is it inverted?

The triangle is upside down:

https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)

◧◩◪
19. mtlync+5B[view] [source] [discussion] 2025-03-28 14:51:45
>>jppope+Wv
Thanks for reading!

>I'm curious, what is the motivation for moving into the content business? I'm certainly interested in this project, and will likely buy the book, etc, but I'm also somewhat disappointed to not see you going after something bigger/harder/technical and sharing that journey. I found your previous work very inspiring.

I'm trying to find a business that lets me write about technical things that I find interesting and have it be financially viable and aligned with my readers' interests.

When I was running TinyPilot, I wanted to write about a lot of what I was doing, but the pace of the business was tough, so I had very little time to write. And after the first few months, my writing didn't have a measureable impact on the business anymore. I liked to think that it did, but it was hard to allocate so much of my time to blogging when I could have been working on other parts of the business.

And it makes sense that blogging wouldn't help TinyPilot much. I think there's overlap between people who read my blog and people who are interested in that product, but it's not super aligned. Like the people interested in running an indie business are not necessarily interested in buying a KVM over IP device.

There are a few different models for making money from blogging (ads, affiliate deals, paid membership). The one that appeals to me most is what Julia Evans[0] does, where she blogs about what she's interested in, but she has paid products[1] that allow readers to contribute back financially.

I'd eventually like to get back to a SaaS or some type of software product, but I'd like to see if I can make the book work, as there's a lot I'd like to teach that I don't see elsewhere.

But in general, I think educational products ("info products") have an unfortunate stigma. I've only done one, but I found it to be a great way to learn about indie businesses because it's a microcosm of the whole process of customer discovery, marketing, and sales. But it has the advantage of not being a long-term promise, so if it doesn't work out, you just move on to the next thing rather than tell all of the early customers who bet on you that you're shutting down and killing off their product.

[0] https://jvns.ca

[1] https://wizardzines.com/

31. dynm+SM[view] [source] 2025-03-28 15:50:18
>>rbanff+(OP)
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.)

Also, props for this stark picture of reality: https://refactoringenglish.com/chapters/write-blog-posts-dev...

◧◩
33. gusmal+YN[view] [source] [discussion] 2025-03-28 15:56:46
>>margin+5r
aka Barbara Minto's Pyramid Principle: https://www.mckinsey.com/alumni/news-and-events/global-news/...
◧◩◪
35. mtlync+iQ[view] [source] [discussion] 2025-03-28 16:09:11
>>eimrin+zK
Haha, none personally but maybe the photographer did. It's a free stock photo.[0]

I hired an illustrator to design a custom cover for me, but the project went off the rails, as the artist was using AI in ways I disliked, so I ended up just doing my own mediocre cover in two hours.[1]

[0] https://unsplash.com/photos/shallow-focus-photo-gray-balance...

[1] https://mtlynch.io/retrospectives/2025/01/#my-poor-experienc...

39. swyx+JW[view] [source] 2025-03-28 16:48:14
>>rbanff+(OP)
just my little contribution as a somewhat known writer: make your titles count https://dx.tips/titles
◧◩
42. swyx+4X[view] [source] [discussion] 2025-03-28 16:50:36
>>Martij+gB
fellow writer here

you can have your cake and eat it too: TLDR, create a multi tier system

do a bunch of short form posts and see what gets abnormal traction from others / gets referenced by YOU more

THEN you invest the time to go the extra yard

this way you dont overinvest in what isnt popular and you also get multiple "shots on goal"

ex: https://www.swyx.io/bottom-up-ideas

◧◩
49. rsync+b01[view] [source] [discussion] 2025-03-28 17:04:28
>>margin+5r
“Inverted pyramid …”

I developed a writing format that I call an “iceberg article”:

https://john.kozubik.com/pub/IcebergArticle/tip.html

… which qualifies as an inverted pyramid but with some additional attributes.

◧◩◪
51. kens+131[view] [source] [discussion] 2025-03-28 17:19:36
>>sunk1s+rr
The "inverted pyramid" first described a visual pyramid, not a conceptual pyramid. I found an 1887 article in Time magazine on journalism, describing the inverted pyramid structure. Specifically, the top of a newspaper article (the display, summarizing the article) consisted of not just the title, but multiple lines of different sizes. First, the title in large capitals. Next, a line of small capitals. Finally, three, four, or more rows of smaller type arranged in the form of an inverted pyramid.

That is, the lines in the heading got progressively shorter, making a visual inverted pyramid, with the most important information first.

Later, the "inverted pyramid" term described the structure of the entire article with the most important parts first, but the metaphor does seem backward.

https://books.google.com/books?id=rNaEw8DwatwC&pg=PA154&dq=%...

◧◩
62. cyndun+ie1[view] [source] [discussion] 2025-03-28 18:32:05
>>avinas+k91
Details: https://github.com/scynthiadunlop/WritingForDevelopersBook
◧◩◪
64. kqr+7h1[view] [source] [discussion] 2025-03-28 18:51:27
>>pansa2+sU
I have noticed that when I wrote blog posts they tend to fall in one of the two categories. Sometimes I'm trying to share an insight, in which case I make sure not to bury the lede[1]. Sometimes it's the journey to the insight that matters more than the insight itself[2], in which case the narrative take precedence, even if it buries the lede.

In some cases it is possible to combine both, by using the storytelling formula that starts describing the outcome and then traces back to how things ended up that way.

[1]: The lede is in the title, even! https://entropicthoughts.com/code-reviews-do-find-bugs

[2]: This is all meandering discovery. https://entropicthoughts.com/deploying-single-binary-haskell...

◧◩◪◨
86. mtlync+dz1[view] [source] [discussion] 2025-03-28 21:20:32
>>tasuki+6y1
>The link on your website says "Write Blog Posts that Developers Read". I'd have expected that to explain _why_ writing blog posts that developers read is worthwhile.

The post is aimed at people who want their writing to reach more developers. If they've reached the article based on the title, I assume they already want to reach more readers, so I don't think it's worth explaining at that point.

If I clicked an article called, "How to vertically center a div using CSS" and the article explained why I might want to center a div, I'd find it kind of strange and not what I want to spend my time reading.

>I write a blog that gets read by no one. When I publish a blog post, I don't check how many people read it. The blog has no particular topic, just whatever random thoughts pop into my head. Yes I'd like to improve my writing, so I can formulate my thoughts better. But I'm a little suspicious of anyone who thinks reaching a big audience is so obvious a goal it doesn't even require explaining why.

I think that's fine, and I support you doing that, but it just means that you're not the audience for this particular post.

I've published several other excerpts on the book's website that are about craft rather than strategy for reaching readers, so you might be interested in those.[0]

[0] https://refactoringenglish.com/chapters/

◧◩◪
87. teddyh+Uz1[view] [source] [discussion] 2025-03-28 21:25:49
>>0cf861+ME
<https://en.wikipedia.org/w/index.php?title=BLUF_(communicati...>
◧◩◪
111. ZYbCRq+n72[view] [source] [discussion] 2025-03-29 01:51:12
>>hk1337+xi1
> what I was taught, in high school ~30 years ago

They should still be teaching it? I don't think much has changed? I went to school a decade ago, and during that time we still wrote essays following these guidelines.

https://owl.purdue.edu/owl/subject_specific_writing/writing_...

https://owl.purdue.edu/owl/general_writing/academic_writing/...

https://owl.purdue.edu/owl/general_writing/the_writing_proce...

---

Also, there are many different forms of writing. People write in forms other than argumentative essays, etc.

115. rednaf+5d2[view] [source] 2025-03-29 03:08:46
>>rbanff+(OP)
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.

[1]: https://rednafi.com/

◧◩◪◨
118. rsync+ch2[view] [source] [discussion] 2025-03-29 04:04:33
>>Noumen+lb2
It is exactly what you expected - click the "body" link and you'll see the entire topic fully expanded:

https://john.kozubik.com/pub/IcebergArticle/body.html

◧◩◪◨
130. n0tqui+2w2[view] [source] [discussion] 2025-03-29 07:28:24
>>margin+Dv
Humour can absolutely feel forced and insecure, however it can be a great tool to help deliver a point. Done well humour can help with the flow of a presentation or text, done badly it jars. You have to know your audience and keep your humour on topic: "street jokes"* are almost never going to work in your favour.

I read a really interesting book* about the topic a while back where the authors delve into why humour works and how to find a style of humour that works for you. Unfortunately there are places imo where they fall into their own trap of trying too hard, but honestly it serves to prove the point.

* https://www.urbandictionary.com/define.php?term=Street%20Jok...

* https://www.humorseriously.com/

132. nuredi+3A2[view] [source] 2025-03-29 08:26:39
>>rbanff+(OP)
It's interesting to see how some of the most popular blogs in https://refactoringenglish.com/tools/hn-popularity do the opposite of what's being suggested here.

Still, for most people who are still finding their style and (for some reason) are optimizing for popularity, this seems like sound advice.

◧◩◪◨
145. Throwa+B93[view] [source] [discussion] 2025-03-29 14:48:23
>>margin+Dv
Steve Yegge's (in)famous Google platforms rant and his other early essays is a counterexample I would think. It was taken down long ago but there's an archived copy at https://gist.github.com/chitchcock/1281611 .
◧◩◪◨⬒
149. stavro+3J3[view] [source] [discussion] 2025-03-29 19:58:14
>>rsync+ch2
A few years ago I wrote an implementation of what you describe: https://skorokithakis.github.io/expounder/
◧◩◪
151. rednaf+b24[view] [source] [discussion] 2025-03-29 22:42:23
>>abbada+ny2
Lots.

>>37192467

>>9266184

[go to top]