Rendered at 17:06:14 GMT+0000 (Coordinated Universal Time) with Cloudflare Workers.
phreack 21 minutes ago [-]
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.
joshkel 24 minutes ago [-]
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.
weinzierl 1 hours ago [-]
"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.
pastel8739 1 hours ago [-]
Is blogging necessarily technical writing?
mtlynch 17 minutes ago [-]
OP here.
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
lapcat 9 minutes ago [-]
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! ;-)
mobilejdral 56 minutes ago [-]
The community yearns for a new stack overflow.
dewey 32 minutes ago [-]
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.
bsuvc 25 minutes ago [-]
Exactly.
StackOverflow was always just an "answer machine".
They wanted it to be a community, but it never was.
esafak 46 minutes ago [-]
Do they? How would it be different?
raincole 23 minutes ago [-]
In 2021 maybe.
Today LLMs have completely replaced the original role of StackOverflow.
rglullis 51 minutes ago [-]
> 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.
abubnov75 1 hours ago [-]
Helpful, thank you. I'm just going to write such an article
all2 1 hours ago [-]
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?
arpanghoshal 6 minutes ago [-]
[dead]
mcphage 40 minutes ago [-]
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".
dewey 34 minutes ago [-]
How would you define the limit above which it's appropriate to share your findings on a given topic on your blog?
antonyt 26 minutes ago [-]
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.
dewey 20 minutes ago [-]
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.
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.
"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)
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.
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.
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
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.
StackOverflow was always just an "answer machine".
They wanted it to be a community, but it never was.
Today LLMs have completely replaced the original role of StackOverflow.
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.