Most active commenters
  • tehjoker(3)

←back to thread

How to write blog posts that developers read

(refactoringenglish.com)
595 points rbanffy | 12 comments | 28 Mar 25 11:01 UTC | HN request time: 0.211s | source | bottom
Show context
marginalia_nu ◴[28 Mar 25 14:01 UTC] No.43505551[source]▶
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.

replies(15): >>43505573 #>>43505719 #>>43506046 #>>43506189 #>>43506400 #>>43506970 #>>43507372 #>>43507727 #>>43508468 #>>43508865 #>>43508960 #>>43513506 #>>43514694 #>>43515583 #>>43516620 #
hk1337 ◴[28 Mar 25 19:00 UTC] No.43508865[source]▶
> 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.

This sounds similar to what I was taught, in high school ~30 years ago, about journalism. When you write an article for the paper, the first sentence should have the who, what, when, where. The reader should be able to get the basic, relevant information from the first sentence then start giving more details as you go along. This is not only for the reader but to make it easier for the editor if/when they need to cut an article short then they can just cut text from the end.

replies(5): >>43509993 #>>43510049 #>>43512017 #>>43515022 #>>43515935 #
1. forrestthewoods ◴[28 Mar 25 21:38 UTC] No.43510049[source]▶
> the first sentence should have the who, what, when, where

I utterly despise modern long form journalism which does not establish any of these things until 1/3 through the article. It’s infuriating.

replies(4): >>43510306 #>>43510309 #>>43511799 #>>43513278 #
2. miki123211 ◴[28 Mar 25 22:04 UTC] No.43510306[source]▶
But aren't you happy when you finally learn that John was wearing Khaki pants and sipping a Latte that he just ordered at a starbucks? /s
3. tehjoker ◴[28 Mar 25 22:04 UTC] No.43510309[source]▶
The articles were intended for you to read. If you find them annoying, maybe they weren't written for you.
replies(2): >>43510370 #>>43512860 #
4. MonkeyClub ◴[28 Mar 25 22:11 UTC] No.43510370[source]▶
> The articles were intended for you to read

Or they were intended for you to scroll further on the page and load more ads and autoplay videos.

Good essays start with their thesis, expand upon that, and conclude by bringing it back to it.

There is no reason journalism should veer away from a format that works for one goal (information dissemination), unless there are other goals at play (longer engagement).

replies(1): >>43510378 #
5. tehjoker ◴[28 Mar 25 22:13 UTC] No.43510378{3}[source]▶
Perhaps novels should be written in the inverted triangle format.
replies(1): >>43510625 #
6. jkmcf ◴[28 Mar 25 22:39 UTC] No.43510625{4}[source]▶
Perhaps there's a difference between fiction and non-fiction
replies(1): >>43512044 #
7. chatmasta ◴[29 Mar 25 01:14 UTC] No.43511799[source]▶
It's not just long form journalism. The basic five-paragraph essay, taught in every school from elementary through university level, violates this principle. When you're learning to write, there is an implicit assumption that you have a captive audience — even if it's limited to your teacher — who is forced to read your work. So there is generally insufficient emphasis on "getting to the point." Instead, you're taught to "grab the reader's attention," with an exciting sentence or visual anecdote. That's what you're seeing in long form journalism that usually starts with some narrative description of a central character in the story.

Whereas in the real world, you are competing for attention, and nobody has to read what you write. So if your goal is to convey information, you better get to the point. But if your goal is to tell a story, then what's the rush?

replies(1): >>43513161 #
8. tehjoker ◴[29 Mar 25 01:55 UTC] No.43512044{5}[source]▶
I think the author can decide how they wish to present their work
replies(1): >>43515652 #
9. forrestthewoods ◴[29 Mar 25 04:57 UTC] No.43512860[source]▶
There are more long form articles available than I have time to read. I hate when a juicy sounding headline grabs my attention, but I have to read for 5 minutes just to figure out what it’s actually about and if I want to keep reading. The disappointment of going from “interesting title” to “vague unimportant flashback” is immense.
10. grandempire ◴[29 Mar 25 06:02 UTC] No.43513161[source]▶
> Whereas in the real world, you are competing for attention, and nobody has to read what you write

Note that this is a cultural artifact relative to our time where marketing and lobbying are so pervasive. Aristotle isn’t written to grab your attention.

11. ako ◴[29 Mar 25 06:29 UTC] No.43513278[source]▶
I feel like most news articles I read miss the why, just like your first sentence.
12. MonkeyClub ◴[29 Mar 25 14:06 UTC] No.43515652{6}[source]▶
But the author has no intent!

(Eng. Lit. /s)