How to write blog posts that developers read

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.

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.

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

The triangle is upside down:

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

>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.

I'll respectfully disagree on this one. You can overdo images, but I think readers find a wall of text intimidating and visually too boring, but this is a matter of taste.

>Images should above all never be funny.

I strongly disagree with this. It's like saying a technical blog post should never have jokes.

Why should an image never be funny?

I think you absolutely can mix humor and useful technical insights. xkcd is probably the best example, but there are lots of authors that complement their writing with humor, both in images and in text.

Mixing humor into serious communication comes at the expense of authenticity. It's difficult to know what an author really means when they mix attempts at humor into the writing (and this is often deliberate, if someone makes a particularly spicy political remark, it's usually in the form of a joke, in order to shield from potential backlash). Overall it's a style of writing that feels sophomoric and insecure, as though the message itself isn't enough so there's a need to crack jokes to compensate. This successfully distracts from the message you're trying to convey, ... at the expense of clarity.

Only if you're authentically humorless. ;-)

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.

You sometimes find texts where you get the feeling the author almost expects a sitcom laugh track over the post, and funnies are crammed into every available crevice.

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"

It's also why LinkedIn posts all sound the same.

"It seemed like any other Monday. Little did I know, it was going to be the day that changed my life forever..."

"Marketing isn't about getting the most traffic. It's about converting the most traffic. A thread:"

> Images should above all never be funny

:)

If you have multiple points that don't both support a larger point, they should probably be split into two separate essays.

Your first example could be the start of an inverted pyramid if the thesis of the post is how the Monday was just like any other. But the next sentence dashes that notion.

The second example could be an example if it quickly follows up with the ways to convert traffic, but better to lead with the novel way(s) to convert traffic, then follow up with why conversion is more important than generation.

Do you find this conflicts with "offering an interesting story that resonates with the reader"?

For example: Using inverted pyramid to describe a problem and my solution, I'd structure my writing as "here's a problem, I found this solution, using this method". Whereas a story would usually be told in chronological order: "here's a problem, I tried these methods, and came to this solution".

Or is it possible to both have your cake and eat it? Tell a good story after giving away the ending?

Jokes in HN comments typically don't play well if the whole point of the comment is to make a joke, but if you make a joke in service of a substantive point or attach a joke to an otherwise meaningful comment, there's usually a good response.

I've come to appreciate HN's cultural norms around jokes because if you compare discussion to something like reddit, the top comment is often just a joke or a pop culture quote and then a massive thread of people just talking about the joke or reference rather than the actual story. I think HN's norms do a better job of fostering curious discussion.

Then each chapter has the same: "Getting in touch" - why stroking your cat soothes your body. Etc

You may even have sections within the chapters and each can follow the same format.

Thousands of years ago it was enough just to write down stuff you've learned, call it "Meditations" and hope people would still be reading it in the distant future.

Now if it's just "stuff I've learned about coding" or "things that make me happy" you're going to need an extremely strong hook to tie that together and build an audience.

So start with a single thesis and decompose from there. Inverted pyramids all the way down :)

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.

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=%...

I think what matters the most is that the reader can tell quickly whether the text is interesting.

You could start by e.g. describing a mystery, and then proceed to reveal the truth later, this sometimes works, though if the payoff isn't there, readers will feel cheated.

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...

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

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.

Why on Earth not? Maybe a blog about conflict in the middle east isn't the place, but a blog sharing stories about the tech industry? Surely some humorous screenshots will add to the experience.

Obviously just throwing in random images totally unrelated to the subject matter would be a huge turnoff, but I cannot think of any reason why you'd take such an absolute position on something so low-stakes.

It also appears insecure and juvenile, as though you're not fully confident that what you are saying will stand on its own without attempts at comedy, and ironically raises questions about the age and experience of the author.

Of course there are exceptions, but as a rule of thumb, I would strongly avoid this pattern of communication.

You went from "Images should above all never be funny," to "You get this jarring tonal whiplash when you add funny images to an otherwise serious text."

Yeah, if a post's text is 100% serious, then yes it would be jarring to insert funny images. Nobody's suggesting you do that, though.

>It also appears insecure and juvenile, as though you're not fully confident that what you are saying will stand on its own without attempts at comedy, and ironically raises questions about the age and experience of the author.

This comes across to me as strangely judgmental and narrow-minded about what good technical writing is.

Joel Spolsky is, in my opinion, the best software blogger of all time. His posts often integrated humor, and I think it definitely heightened rather than detracted from his writing.

Look at the bloggers who are most popular on HN: Paul Graham, Julia Evans, Simon Willison, Rachel Kroll, Terence Eden. All of them often use a lighthearted style and integrate humor, often with humorous images as well.

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

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).

It also breaks the flow. Reading from long form text and then skipping to image and parsing the text breaks the mental flow, for me at least, and there never seems to be a clean place to do it.

I would expect the "a monad is just a monoid in the category of endofunctors, what's the problem" article to include humorous images. I would expect a serious tutorial about monads to not do so.

Cut literally - I worked on a student newspaper (with professional phototypesetting gear, comparable to the city papers - AKI Ultrasystem) and second-tier "filler" content was just set in a single long column, then pasted up on the layout boards (hot wax as the adhesive) and then trimmed when it ran out of space (with an x-acto blade.) Reading that class of content was kind of optional for the layout editor, at least at 10:30pm when trying to get the boards out the door for an 11pm press deadline...

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?

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.

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

“How I Reduced My Postgres Query Latency By 100x With A Single Index”

Even in the title, I can tell you the punchline (if you wanna make your DB access faster, use an index!)

but an interested reader still wants to figure out how exactly your solution works, and you can tell them some interesting details along the way

“just enforcing unique constraints does help certain data types, but it’s not a big performance boost most of the time”

while finishing on the kicker

“Since my hottest endpoint by far was for individual users querying orders which were still ongoing, I created an index on the user field for the orders table, and included a status filter in the index, which took p90 latency from 10s to <100ms!”

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.

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/

It is among the few useful things I learned at the university.

(Eng. Lit. /s)

The disconnect here is what is the meaning of the "width" of the triangle/pyramid in the analogy.

The idea in the journalistic inverted pyramid concept is that the width of the pyramid correlates to the importance of the information.

So you start first with the most important information (the base of the pyramid, at the top) and then as you continue you fill in the details that may be interesting and necessary to support the important information, but not necessarily important on their own (the tip of the pyramid, at the bottom)