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.
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."
"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.
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.
> 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.
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 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.
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)
OP here.
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
"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 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 community yearns for a new stack overflow.
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.
In 2021 maybe.
Today LLMs have completely replaced the original role of StackOverflow.
Do they? How would it be different?
> 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.
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".
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.
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?