Most active commenters
  • marginalia_nu(3)

←back to thread

How to write blog posts that developers read

(refactoringenglish.com)
595 points rbanffy | 11 comments | 28 Mar 25 11:01 UTC | HN request time: 0.533s | 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 #
1. sunk1st ◴[28 Mar 25 14:04 UTC] No.43505573[source]▶
Wouldn’t that be a regular pyramid? In what sense is it inverted?
replies(5): >>43505633 #>>43505671 #>>43505690 #>>43506000 #>>43507903 #
2. Galanwe ◴[28 Mar 25 14:09 UTC] No.43505633[source]▶
That seems intuitive to me, but I guess it depends how you picture it.

I think of a pyramid from the ground up, so a dense base followed by a thinner top.

A inverted pyramid would be thin first then dense and large.

When reading though, you go from top to bottom, so if you're more visual instead of time based, you may see it the other way around.

3. marginalia_nu ◴[28 Mar 25 14:12 UTC] No.43505671[source]▶
It's not my name for it, but an established term for the style, so I wouldn't know.

I would note that most pyramid metaphors tend to be kind of lacking. Test pyramid, food pyramid, etc.

4. jasode ◴[28 Mar 25 14:14 UTC] No.43505690[source]▶
> In what sense is it inverted?

The triangle is upside down:

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

replies(1): >>43505938 #
5. azornathogron ◴[28 Mar 25 14:33 UTC] No.43505938[source]▶
It's funny because from that diagram I really don't see any particular relationship between the shape and its content. You could draw a regular pyramid with three segments and write the same labels on it and it would make just as much sense to me.

If anything a regular pyramid makes more sense to me: you want the smallest/narrowest useful description at the top and then you gradually expand on it as you go down, providing more (wider) context and detail for the key information.

Edit: Of course, it's a widely used term and good to understand in that context; the Wikipedia link is useful.

replies(3): >>43505959 #>>43506097 #>>43508845 #
6. marginalia_nu ◴[28 Mar 25 14:35 UTC] No.43505959{3}[source]▶
Yeah, this seems to be true for most pyramid models. It's really annoying when you start to spot it.
7. tantalor ◴[28 Mar 25 14:39 UTC] No.43506000[source]▶
It's a bad metaphor.

In the "inverted pyramid" the most important information (which should come first) is represented by the base, which is the biggest part of the pyramid and holds up the rest of the pyramid. In a sense, it is the foundation, so you have to "get it right".

The analogy is "base = big = foundational = important"

Personally I think that's confusing, because you just as easily say the tip of the pyramid should represent the most important information, which should be conveyed concisely and without extraneous detail or background.

In that case the analogy would be, "tip = concise = main point = important"

replies(1): >>43508457 #
8. wonger_ ◴[28 Mar 25 14:47 UTC] No.43506097{3}[source]▶
I think it's about laying foundations at the beginning, not the length of the text at the beginning. The first sentence/paragraph is the foundation of everything beneath it, whereas the base of a normal pyramid is the foundation of everything above it.
9. kens ◴[28 Mar 25 17:19 UTC] No.43507903[source]▶
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=%...

10. irrational ◴[28 Mar 25 18:16 UTC] No.43508457[source]▶
That is confusing. In my mind, the tip of the pyramid is the smallest part of the pyramid, just like the brief overview at the beginning of the post is the smallest part. The base of the pyramid is the biggest part of they pyramid, so that is the bulk of the post where it goes into detail.
11. kqr ◴[28 Mar 25 18:58 UTC] No.43508845{3}[source]▶
> I really don't see any particular relationship between the shape and its content.

This is often the case with geometric metaphors. They catch on easily, but they rarely make a lot of sense on closer scrutiny.