I always insist that education is not storytelling and should not be structured as such. People want to save "twists" and "revelations" for maximum impact and it's harmful. It should actually be the other way around and be, keeping the theme, "spoilery" and repetitive. Like a good presentation you should start by saying what you'll say, say it, then conclude by saying what you said.
LLMs have made this problem extremely worse. Imagine how'd you'd explain what an MCP is in a couple words and technically, then try to look it up. There's phone books worth of pages and text that never end up getting to the point.
I agree that education is not storytelling, but I think that storytelling can be a useful tool for education.
A lot of Paul Graham and Joel Spolsky posts don't get straight to the point and usually do not follow an intro -> body -> conclusion format. A lot of them start with a story that makes the direction of the post unclear[0] or include long digressions whose value isn't immediately obvious.[1]
For a while, I struggled with this contradiction because I think good writing should quickly demonstrate the value a reader can expect, but I think Graham and Spolsky are excellent writers that frequently take their time in getting to their point.
The easy answer is that Graham and Spolsky are famous, so they can do whatever they want, and people will still read. I've come to think it's actually that writers like Graham and Spolsky are so good that the quality of the writing itself is the thing of value that keeps you interested even if you don't know what point they're going to make.
There is a balance. A short story can help understand. However you can go too far with stories. Joel strikes a good balance because it isn't long before you realize why the story is relevant and he cuts out a lot of details that are not relevant. He also is telling non-fiction stories, which adds additional credibility (unlike many blogs that are making up fiction stories)
Over the years, readers learned what to expect from Joel and Paul, which gave them freedom to continue writing in their own style. I'm curious how the same writing would be received today in a very different environment - much more crowded and driven more by social media than the open web, not to mention the shift of attention towards video. I just don't think writers today have access to the attention that tech bloggers of an earlier era built up.
My undergraduate research advisor told me "Papers and presentations are not murder mysteries." I try to keep that in mind whenever I approach explanatory writing, because the purpose is to help the audience reach understanding of where you ended up, not to replicate the epiphany you had yourself.
Heh. Mine, before the diploma defense, literally told me "Assume that the panel knows everything about the math except for the stuff your did in your thesis, so tell them about that. Don't bother explaining what 'error correction codes' are, tell them about your specific construction and practical boundaries you've determined". Which, I guess, is precisely "the reader knows everything I know except this one thing" antipattern but then again, blogging is different from e.g. conference presentation, isn't it?
While I understand where you are coming from, I think some of those are subjective.
I personally prefer articles that link to other(better) sources for definining concepts instead of trying to explain everything.
So several times I read articles like a stack, starging with A, then in the middle going to B and after finishing B going back to A. It doesn't bother me at all. It actually says to me that the author understands they cannot be experts on everything and recognize other articles.
I also enjoy articles with reveal their twist late if they are not super long.
On my personal blog I am actually writing both styles (just explain right away, or build up to something that will become clear later in the article)
Last week, after following an HN link, I found myself thinking that tech blogs were starting to need that "Jump to Recipe" link that has taken over the food blogging world (for the better).
"The meandering intro" might be the most common mistake, by far, but the most damaging mistake, by far, is the failure to connect the topic with something the readers are familiar with (anti-pattern #2). Some things simply require a certain level of expertise/prerequisites to begin to understand, but I've repeatedly seen in software blogging, READMEs, etc. a failure to answer "what is this, compared to what I'm familiar with, and if I'm not familiar with anything relevant, why should I want to be?"
This applies to almost everything in the software space. New tool? New design pattern? New library? Language idiom? Language? Or, for more modern takes, new model? New harness? New harness option? New use pattern? Give a brief summary of what a project looks like without it, to convey the problem that its existence alone is solving. Then go into the details of how it might compare to other solutions.
Maybe it's just a specific way of how my brain works that finds this sort of information intuitive, and the lack of it particularly annoying.
This is a pet peeve of mine when there is a news story, opinion piece, case study where they spend like several paragraphs (or much more) telling story like it was a novel when in reality you it about maybe one or two paragraphs explaining what happened to a particular person/couple/family etc. and then get into the facts.
It is a massive turn off for me and I just simply close the window if I find they don't get start getting to the point.
I am much more forgiving if the meandering intro is done by someone that is clearly just someone writing up their own work.
I dunno. I know it makes me an enemy of humanity and all, but LLMs have mostly replaced Stack Overflow and dev blogs for me. A dialog with something that writes well (or can take a totally different swing at an explanation if the first one isn't so good), has expert-level knowledge, and isn't egotistical. But maybe most of all the dialog part.
Anyway, I'm learning so much more so much better than I ever have before. Turns out the ultimate slop tools are also the ultimate learning tools if you use 'em right.
It doesn't really, as you can see in their traffic numbers. People are not stopping to use it because they dislike the platform (Most people would not even be aware of any moderation criticism, especially if they are just readers).
People are not using it any more as any AI assistant will give you the answer in seconds, perfectly adapted to your use case and with an easy way to ask follow up questions.
Regarding "The meandering info," I found this advice very helpful:
"The sole purpose of the first sentence is to get you to read the second sentence. The sole purpose of the second sentence is to get you to read the third sentence… and so on."
Sure, if you want empty, soulless writing, akin to TikTok mind-rot and engagement bait. Get your reader's emotions up so they hate-read it. A/B test your blog for which sentences, jokes, and moral stances get the most engagement. Sell your soul to the lowest common denominator. To fight the AI slop, you must become the AI slop.
Or write something that actually provides value to your reader, communicate that value effectively, and trust your reader to recognize that value. Which would you rather read: writing that was optimized for psychologically capturing your eyeballs, or writing that was optimized for providing you something of value?
I find that I'm actually not that picky when it comes to reading technical material, at least in blog form. There's very few pieces I dropped because of how they were written.
Steve Kalabnik gave me similar feedback a year ago,[0] and I'm curious about your reading style because that feels so alien to me.
If you click on a blog post, and the writing is poor or seems LLM-generated, you keep reading? Or do you mean that you're willing to forgive more superficial things like meandering or excessive formality if the post has other redeeming qualities?
As an example, I clicked a post a few weeks ago about orchestrating Claude Code sessions[1], as that's a topic I'm interested in, but I found the writing so poor that I felt like the post was either LLM-generated or written for someone who had different needs than I did. Would you read a post like that to completion if the topic interests you?
> From the reader’s perspective, there are a billion other articles they could be reading. Why should they read yours?
I'd rather read something that shows any semblance of personality than yet-another engagement/reach/marketability-optimized "article" that just follows all the established tropes and could be written by any drone or clanker.
This is something I see a lot too, and I almost covered it in the post. I think it goes hand in hand with excessive formality where people think that if you're writing a blog post about something, you have to be an authority on the topic, but that's not true.
It's valuable and useful to write about things when you're still a beginner as long as you present yourself as a beginner. Julia Evans does this extremely well. My favorite example is "Some notes on using nix,"[0] which got me to start using Nix when I'd seen lots of other posts from more experienced Nix users that were too in the weeds for me to understand. But the way Julia approaches it is that she's learned a little bit more than someone who's never touched it, so you can read her progress and get a slight head start from where you would have started without her notes.
Not OP, but it's the "as if I were an expert" part that rankles. It's fine to share your experiments and learning projects, but frame them as such. Some writers present their imperfect weekend experiments as if they're doing us a favor by giving out their genius for free.
Sometimes it's very easy to be confident about your expertise if you are not aware of all the complexities of a problem (See programmers and their assumptions about names and dates). So my point is a bit that it's very hard to judge that and I'd rather have someone share their learnings on their personal blog without hesitation and feeling the need to gate-keep blogging.
> I'd rather have someone share their learnings on their personal blog without hesitation and feeling the need to gate-keep blogging.
I understand what you're saying, but often well-written articles end up getting passed around and relied upon as if they were well supported documents. I don't know if it's as common now, but the Rails community went through waves of fads as someone wrote an article and then everyone read it, and started following what it said, when often it wasn't good advice in the first place.
It got the point where, if you looked at an old enough codebase, you could get a rough sense of how old some code was by looking at whatever fads it contained, and look back to see when that coding quirk was popular.
I always insist that education is not storytelling and should not be structured as such. People want to save "twists" and "revelations" for maximum impact and it's harmful. It should actually be the other way around and be, keeping the theme, "spoilery" and repetitive. Like a good presentation you should start by saying what you'll say, say it, then conclude by saying what you said.
LLMs have made this problem extremely worse. Imagine how'd you'd explain what an MCP is in a couple words and technically, then try to look it up. There's phone books worth of pages and text that never end up getting to the point.
I agree that education is not storytelling, but I think that storytelling can be a useful tool for education.
A lot of Paul Graham and Joel Spolsky posts don't get straight to the point and usually do not follow an intro -> body -> conclusion format. A lot of them start with a story that makes the direction of the post unclear[0] or include long digressions whose value isn't immediately obvious.[1]
For a while, I struggled with this contradiction because I think good writing should quickly demonstrate the value a reader can expect, but I think Graham and Spolsky are excellent writers that frequently take their time in getting to their point.
The easy answer is that Graham and Spolsky are famous, so they can do whatever they want, and people will still read. I've come to think it's actually that writers like Graham and Spolsky are so good that the quality of the writing itself is the thing of value that keeps you interested even if you don't know what point they're going to make.
[0] https://www.joelonsoftware.com/2000/04/06/things-you-should-...
[1] https://paulgraham.com/worked.html
There is a balance. A short story can help understand. However you can go too far with stories. Joel strikes a good balance because it isn't long before you realize why the story is relevant and he cuts out a lot of details that are not relevant. He also is telling non-fiction stories, which adds additional credibility (unlike many blogs that are making up fiction stories)
Over the years, readers learned what to expect from Joel and Paul, which gave them freedom to continue writing in their own style. I'm curious how the same writing would be received today in a very different environment - much more crowded and driven more by social media than the open web, not to mention the shift of attention towards video. I just don't think writers today have access to the attention that tech bloggers of an earlier era built up.
My undergraduate research advisor told me "Papers and presentations are not murder mysteries." I try to keep that in mind whenever I approach explanatory writing, because the purpose is to help the audience reach understanding of where you ended up, not to replicate the epiphany you had yourself.
Heh. Mine, before the diploma defense, literally told me "Assume that the panel knows everything about the math except for the stuff your did in your thesis, so tell them about that. Don't bother explaining what 'error correction codes' are, tell them about your specific construction and practical boundaries you've determined". Which, I guess, is precisely "the reader knows everything I know except this one thing" antipattern but then again, blogging is different from e.g. conference presentation, isn't it?
In journalism this is called “burying the lead.”
While I understand where you are coming from, I think some of those are subjective.
I personally prefer articles that link to other(better) sources for definining concepts instead of trying to explain everything.
So several times I read articles like a stack, starging with A, then in the middle going to B and after finishing B going back to A. It doesn't bother me at all. It actually says to me that the author understands they cannot be experts on everything and recognize other articles.
I also enjoy articles with reveal their twist late if they are not super long.
On my personal blog I am actually writing both styles (just explain right away, or build up to something that will become clear later in the article)
Last week, after following an HN link, I found myself thinking that tech blogs were starting to need that "Jump to Recipe" link that has taken over the food blogging world (for the better).
"The meandering intro" might be the most common mistake, by far, but the most damaging mistake, by far, is the failure to connect the topic with something the readers are familiar with (anti-pattern #2). Some things simply require a certain level of expertise/prerequisites to begin to understand, but I've repeatedly seen in software blogging, READMEs, etc. a failure to answer "what is this, compared to what I'm familiar with, and if I'm not familiar with anything relevant, why should I want to be?"
This applies to almost everything in the software space. New tool? New design pattern? New library? Language idiom? Language? Or, for more modern takes, new model? New harness? New harness option? New use pattern? Give a brief summary of what a project looks like without it, to convey the problem that its existence alone is solving. Then go into the details of how it might compare to other solutions.
Maybe it's just a specific way of how my brain works that finds this sort of information intuitive, and the lack of it particularly annoying.
"The meandering intro"
Not only the intro. Many bloggers try to write as if they'd writing a story, building suspense and all. For technical writing, don't bury the lede.
Is blogging necessarily technical writing?
The article is about software blogging, so essentially yes.
But also in the case where the writing is actually not technical, then... obviously the parent comment's complaint wouldn't apply? C'mon.
This is a pet peeve of mine when there is a news story, opinion piece, case study where they spend like several paragraphs (or much more) telling story like it was a novel when in reality you it about maybe one or two paragraphs explaining what happened to a particular person/couple/family etc. and then get into the facts.
It is a massive turn off for me and I just simply close the window if I find they don't get start getting to the point.
I am much more forgiving if the meandering intro is done by someone that is clearly just someone writing up their own work.
The community yearns for a new stack overflow.
I dunno. I know it makes me an enemy of humanity and all, but LLMs have mostly replaced Stack Overflow and dev blogs for me. A dialog with something that writes well (or can take a totally different swing at an explanation if the first one isn't so good), has expert-level knowledge, and isn't egotistical. But maybe most of all the dialog part.
Anyway, I'm learning so much more so much better than I ever have before. Turns out the ultimate slop tools are also the ultimate learning tools if you use 'em right.
It doesn't really, as you can see in their traffic numbers. People are not stopping to use it because they dislike the platform (Most people would not even be aware of any moderation criticism, especially if they are just readers).
People are not using it any more as any AI assistant will give you the answer in seconds, perfectly adapted to your use case and with an easy way to ask follow up questions.
Exactly.
StackOverflow was always just an "answer machine".
They wanted it to be a community, but it never was.
Do they? How would it be different?
In 2021 maybe.
Today LLMs have completely replaced the original role of StackOverflow.
Where will the LLMs get information about new tools, programming language or problems in general?
They can read the web/repos just like anyone else.
Regarding "The meandering info," I found this advice very helpful:
"The sole purpose of the first sentence is to get you to read the second sentence. The sole purpose of the second sentence is to get you to read the third sentence… and so on."
(quoted from https://thehustle.co/write-like-hustle-boring-stuff-writing-...; the original idea is apparently from Joseph Sugarman)
Sure, if you want empty, soulless writing, akin to TikTok mind-rot and engagement bait. Get your reader's emotions up so they hate-read it. A/B test your blog for which sentences, jokes, and moral stances get the most engagement. Sell your soul to the lowest common denominator. To fight the AI slop, you must become the AI slop.
Or write something that actually provides value to your reader, communicate that value effectively, and trust your reader to recognize that value. Which would you rather read: writing that was optimized for psychologically capturing your eyeballs, or writing that was optimized for providing you something of value?
https://www.youtube.com/watch?v=vtIzMaLkCaM
I find that I'm actually not that picky when it comes to reading technical material, at least in blog form. There's very few pieces I dropped because of how they were written.
Steve Kalabnik gave me similar feedback a year ago,[0] and I'm curious about your reading style because that feels so alien to me.
If you click on a blog post, and the writing is poor or seems LLM-generated, you keep reading? Or do you mean that you're willing to forgive more superficial things like meandering or excessive formality if the post has other redeeming qualities?
As an example, I clicked a post a few weeks ago about orchestrating Claude Code sessions[1], as that's a topic I'm interested in, but I found the writing so poor that I felt like the post was either LLM-generated or written for someone who had different needs than I did. Would you read a post like that to completion if the topic interests you?
[0] https://lobste.rs/s/youq7y/how_write_blog_posts_developers_r...
[1] https://news.ycombinator.com/item?id=49772806
OP here.
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
Friday will be the 20th anniversary of my first blog post, and I will continue to write sequels to my previous blog posts, and you can't stop me! ;-)
> From the reader’s perspective, there are a billion other articles they could be reading. Why should they read yours?
I'd rather read something that shows any semblance of personality than yet-another engagement/reach/marketability-optimized "article" that just follows all the established tropes and could be written by any drone or clanker.
Helpful, thank you. I'm just going to write such an article
Wait, do you intend to implement each anti pattern into a single article? Or do you intend to write an article with none of these anti patterns?
My biggest pet peeve: "Here's this thing I did once, and now I'll tell everybody how to do it as if I were an expert".
OP here.
This is something I see a lot too, and I almost covered it in the post. I think it goes hand in hand with excessive formality where people think that if you're writing a blog post about something, you have to be an authority on the topic, but that's not true.
It's valuable and useful to write about things when you're still a beginner as long as you present yourself as a beginner. Julia Evans does this extremely well. My favorite example is "Some notes on using nix,"[0] which got me to start using Nix when I'd seen lots of other posts from more experienced Nix users that were too in the weeds for me to understand. But the way Julia approaches it is that she's learned a little bit more than someone who's never touched it, so you can read her progress and get a slight head start from where you would have started without her notes.
[0] https://jvns.ca/blog/2023/02/28/some-notes-on-using-nix/
> It's valuable and useful to write about things when you're still a beginner as long as you present yourself as a beginner.
Yep, I agree with this.
How would you define the limit above which it's appropriate to share your findings on a given topic on your blog?
Not OP, but it's the "as if I were an expert" part that rankles. It's fine to share your experiments and learning projects, but frame them as such. Some writers present their imperfect weekend experiments as if they're doing us a favor by giving out their genius for free.
Sometimes it's very easy to be confident about your expertise if you are not aware of all the complexities of a problem (See programmers and their assumptions about names and dates). So my point is a bit that it's very hard to judge that and I'd rather have someone share their learnings on their personal blog without hesitation and feeling the need to gate-keep blogging.
> I'd rather have someone share their learnings on their personal blog without hesitation and feeling the need to gate-keep blogging.
I understand what you're saying, but often well-written articles end up getting passed around and relied upon as if they were well supported documents. I don't know if it's as common now, but the Rails community went through waves of fads as someone wrote an article and then everyone read it, and started following what it said, when often it wasn't good advice in the first place.
It got the point where, if you looked at an old enough codebase, you could get a rough sense of how old some code was by looking at whatever fads it contained, and look back to see when that coding quirk was popular.
[flagged]
[dead]