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.
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-...
Right, all good (human) communication boils down to both the author and the reader having a theory-of-mind for one-another. The writer must anticipate what a reader will be thinking, and a reader must imagine [0] what the writer wanted to convey.
That's part of what makes the modern epidemic of LLM slop so frustrating: The correctly-formed words make us waste effort trying to reconstruct a mind that was never really there.
0) https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...
If you're writing on your personal blog then take all of this with the size of salt crystal you feel it deserves. Personally, that's about the size of an Acme safe hanging over a cliff waiting for an unsuspecting listicle writer^h^hcoyote.
Maybe someone can tell the LLM's about these anti-patterns, like, seriously, would it help?
I'd prefer of course if people just actually themselves wrote the text that they expect me to read my human self.
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.
Bezos has a sharp mind and often got impatient with the paper for not getting to the point quickly enough. He would deal with the boredom by highlighting all the mistaken assumptions and errors in the paper, which would often derail the meeting.
One VP came up with a way to deal with that. His advice was to write the paper as if the reader was an expert in the field--no definitions, no preamble, just assume the reader already knows.
Then remove every other paragraph.
The result was a paper that forced Bezos to focus and think about every sentence just to understand it. That made it easier to get his agreement at the end.
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.
But also in the case where the writing is actually not technical, then... obviously the parent comment's complaint wouldn't apply? C'mon.
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 find that LLM-written software blog posts generally spend like 3x as many words as would be ideal, but of course take a lot more editing and care.
And, allow me to add antipattern no. N, in full display in the posts below: A 1:1 ratio of main body to footnotes, because we want some place to put all the spicy asides and hot takes.
What to do, my brain struggles with brevity :)
Exhibit A:
Exhibit B:
Exhibit C:
Exhibit D:
(edit: reorder + fix formatting for clarity)
I can understand the position that you do care about other people reading your post, but you weight your own enjoyment of your posts more heavily than anything else, but I'm skeptical of the claim that you don't care who reads your posts.
Honestly, I think there is value in having lived in "idiot mode", because that is the feeling I walk around with most of my life. And thinking is hard, so I don't want to, most of the time, but then I have to, because who will pay my bills otherwise?
Some of those posts are, in fact, because I felt like an uncomprehending idiot, about the blog post's topic, for the longest time ever. And it turned out that I was holding it completely wrong, or had pop-cultured myself into a prejudiced (therefore uninformed) opinion. Then, once some clarity arrived, I wanted to spool it to disk before it evaporated again. And lo and behold, post emerges.
Not everything is a product.
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)
I start with the conclusion in the first paragraph[1], and the user can decide if it’s worth their time or not. Unless you’re Gabriel Garcia Marquez, no one’s going to read your rambling.
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.
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.
Today LLMs have completely replaced the original role of StackOverflow.
If the LLMs could get the same results by just reading documentation and source code, then the content on programming forums would be worth nothing, yet AI companies scrape them constantly... why?
Do we have reason to think that they scrape them more often than they scrape other stuff? (Honest question, I have no idea.)
Doesn't Stackoverflow exist because people can in fact not read the documentation or source code, at least not to the point where it helps them understand their problem.
Yes; not sure how this is relevant to LLMs. One of the most impressive things I've seen change in the last few months is that they don't think twice about cloning a repo of linked-to-my-app code to analyze it to determine a solution. Or even disassemble closed-source object code to find an answer!
With agentic speed/capability, the calculus of "eh let's experiment and explore from the outside a little first" vs. "let's just read the dependencies (whose codebases I'm not familiar with), potentially including the binary itself, and figure out exactly what's going wrong" changes. So I think what's valuable in terms of ancillary info for technical topics is changing.
"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)
Otherwise you end up with an article whose sole purpose is getting you to read it to its end, without accomplishing anything other than wasting your time.
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 really didn't mean to encourage emotional manipulation, soulless optimization, listicles, etc., although I agree that a lot of writing online falls in that bucket, and it's even likely that the advice I uncritically quoted was aimed at that bucket.
I obviously should have thought more carefully and written more clearly.
But I don't think that "Write each sentence to give the reader a reason to keep reading" and "Actually provide value to the reader" have to be mutually exclusive. Instead, I think of it as (like you said) communicating the value effectively: dispense with the throat-clearing, meandering intros, irrelevant personal details, weak thesis statements, etc., and write tight, well-crafted prose that respects the time and honestly maintains the interest of those who'd benefit from the value you can provide. (I certainly don't claim to be an expert here! Appreciate the video link.)
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
When bloggers say, "I don't want to write about topic X because person Y already wrote the definitive post about it," I say, "However good the existing article is, there will still be people that prefer yours." Even if the other person is smarter, more knowledgeable, whatever, you're going to explain it in your own way, and that's going to resonate with a distinct set of people than any other article out there.
I think your anti-patterns apply very well to the stereotypical SWE or HN reader, and if that is who you are targeting, you should absolutely follow these. But the biggest anti-pattern of all is following these anti-patterns while hoping to appeal to the untypical SWE or HN reader.
> I think your anti-patterns apply very well to the stereotypical SWE or HN reader, and if that is who you are targeting, you should absolutely follow these. But the biggest anti-pattern of all is following these anti-patterns while hoping to appeal to the untypical SWE or HN reader.
Can you share more about what you have in mind?
I feel like these recommendations apply outside of software/HN. Like if I had a way to reach knitting bloggers, I'd imagine most of the concepts would be the same with different specifics.
Do you have a software blogger in mind that writes well but doesn't match what I describe in the post?
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...
This! Well, kind of!
I definitely do some type of screening for pieces that I read: I may look up who the author is or what they've worked on; the piece may have been recommended by someone else I respect on social media; the topic itself may have little other writing on it online which signals that it may contain original thought, it may have been up-voted on HN and had interesting comments, etc.
That is to say, I try to evaluate whether it's worth my time reading the article in full, even as I start reading it. I do have a habit of saving URLs of things I read, and typically jot down a few personal notes in a local .md as I read along.
I do use LLM writing as a negative signal: it could be that the author hasn't spent that much time thinking about the issue, and I can spend that time reading something else from my reading list. But there's definitely been a few cases where I read pieces in full, even though they were clearly heavily LLM assisted, only because the material just seemed worth tanking through for.
Perhaps, rephrased: I seldom drop pieces because of the prose, more often I do so because it lacks substance. And, to add, it could entirely be my selective process that leads me to dropping articles less!
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.
[0] https://jvns.ca/blog/2023/02/28/some-notes-on-using-nix/
Yep, I agree with this.
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.
One way to make this even better is to include your questions about things you don't know. "I wonder if that means X or Y, perhaps one way to tell would be investigating it with method Z, whihc I haven't had time to do yet, I wonder if anyone else has or knows."