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.

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.

It may be worth noting that there are historical reasons why newspapers in particular used that format, especially wire copy. The idea was that, in layout, typeset stories could be cut at more or less an arbitrary point. Magazine stories are much less likely to follow this exact format although they still tend not to completely bury the lede.

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

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

The articles were intended for you to read. If you find them annoying, maybe they weren't written for you.

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

Perhaps novels should be written in the inverted triangle format.

Perhaps there's a difference between fiction and non-fiction

> cut at a more or less arbitrary point

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

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?

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

I think the author can decide how they wish to present their work

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.

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

Yeah. I was on a student paper and then actually co-founded one at a different school. At the time I don’t we used wire service copy in either case but you still needed to make stuff fit.

I feel like most news articles I read miss the why, just like your first sentence.

The inverted pyramid principle is like a cold shower: it feels harsh at first but is overall good for your fitness as a writer, as it requires you to 1) understand your own main idea and distil it, which is not always easy if you are not writing a factual news story, and 2) not indulge and get to that distillation immediately, allowing the reader to stop whenever they reach the level of detail they want, which may not jive well with a “free” ad-based publication model but is absolutely reasonable in a subscription-based model (which is, I suppose, where the rule originated).

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

But the author has no intent!

(Eng. Lit. /s)

Ok, but isn't pyramid the point at the top, and inverted pyramid is the point is at the bottom? Have I been looking at the wrong pyramids my whole life?

No you looked at pyramids the right way.

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)

So it's precisely the opposite. Wonderful. I suppose I shouldn't expect anything different, after a few decades of seeing these opposite interpretations arise in parallel.