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.
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.
I think you are getting confused with the format for the reader. Someone looking for a light read would prefer a entertaining read with the twist of learning something, someone looking to learn something will be annoyed at your prose and narration style. What you write is aimed, whenever you like it or not, to a person in a particular state of mind. The motivated to learn will want you to not tell them about your grandma when they are reading the stupid recipe.
I think that's a factor as well. If the reader has a specific goal in mind, and your blog post presents itself as a way for the reader to satisfy their goal, then the reader will probably have less patience for stories.
But to take Spolsky's "Things You Should Never Do" as an example, obviously nobody's Googling, "things to never do," clicking Joel's article, and then getting annoyed at Joel for not telling them immediately. They're finding the post on HN, RSS readers, forums, etc., where they didn't have a specific goal in mind beyond learning/entertainment, so the author has more room to take their time.
I would argue that Joel and Paul's blogs are not education, they are opinion pieces. The fact that many of these opinions have become widely accepted over time doesn't change the format, which is that they are argumentative writing rather than purely informative (as you'd find in a textbook or scientific paper).
And this is exactly what the article fails to account for... they make several blanket assertions that may well make sense for certain types of posts but may not for others.
My 2c is that rule #0 of writing advice should be to take all writing advice with a grain of salt and an eye towards context and audience.
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)
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?
Yeah, deciding on your assumptions about the audience's prior knowledge is one of the toughest parts of presenting information well, I think. If you give too much info, you come across as boring or patronizing; if you don't give enough info, most (if not all) of your audience will rapidly lose interest. But it's all gotta be based on your exact audience in the moment, and that's really hard to take into account a lot of the time.
When writing text, you have the advantage of being able to link to another text. In principle academic citations form a DAG that allows you to understand all prerequisite knowledge for any given paper. Your paper is expected to cite everything it depends on that isn't common knowledge but doesn't need to re-explain it.
> Yeah, deciding on your assumptions about the audience's prior knowledge is one of the toughest parts of presenting information well, I think.
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. Like some animals encountering an extremely realistic plastic fake that we cannot eat/mate-with.
Papers are written to peers. It shouldn't be a "murder mystery" for them (that doesn't mean it shouldn't tell a story). You have to write to your audience. If a paper was written to a general audience, instead of peers, every paper would have to be a novel.
I'll admit that sometimes I'm frustrated with HN comments on arxiv articles. Despite being a nerdy forum most papers aren't written for this audience. Hell, I have a PhD and most papers aren't written for me. Nor should they. I'm perfectly okay if I don't understand a paper. Arguably the hardest thing about a PhD is learning to be comfortable with being dumb and willing to work on becoming less dumb (you're never not dumb, only less dumb)
That's true, but I think scientific writing often veers too hard towards impenetrability. At least in machine learning, many of the hallmark papers are remarkably clear and simple in a way that most papers I read day-to-day aren't. Even something as simple as the problem setting can be written insightfully in a strong piece of work.
Honestly, I feel the opposite. But maybe that's because my doctorate is in ML. But we might also have a different definition of what the hallmark papers are. Many of the well known papers are ones that model scaled an existing method (ViT and ddpm are good examples). Important papers, but in which sense? I do think we have space for all types of papers and written to different audiences, but I don't think we should punish papers just because they're written to their niche domain. In the past decade there's been a huge increase in citation farming and I don't think that helps. Math is probably too much on one extreme but I think ML is on the other. You have to write your papers so a first year PhD can understand, because they're the ones reviewing your work. I don't think that's a desirable outcome
I was handed the paper: A rational design process, how and why to fake it [0]. It's still one of my favorit papers. Basically it tells you to, when writing documentation, go back and put in later findings in the place it would been, if the world had been completely rational. Just leave out all the weaving and late discovery, very few people cares. Retrofit documentation to pretend that everything and everyone was completely rational and had all the knowledge at the correct times. It can cut down documents by a lot.
My PhD advisor said something similar, but he also said papers tell a story. There are a lot of stories that aren't murder mysteries nor suspense novels. Your paper shouldn't be a novel and especially not a suspense one
Following the sequence of a-ha moments in a field is often a useful way to make them happen in the student: at first people thought things stopped after you pushed on them, but then Newton and Galileo realised this was because of a thing called friction, and if there wasn't any friction things wouldn't stop, and this means if you shift your perspective you can change how fast things moved. Later on Maxwell found his equations implied a speed of electromagnetic waves, such as light, but couldn't figure out what perspective it was in. Michelson and Morley tested it and strangely found it was true in all perspectives at once, Einstein made mathematical sense out of that which causes weird effects like time dilation, and our GPS satellites prove time dilation is true.
If I am reading a cookbook, tutorial, or reference to teach myself quickly so that I can accomplish something specific, I completely agree with you. Blog posts can teach something, of course, but when I choose to read a blog, I am hoping to experience a bit of the writer's personality and to be entertained in the process. Storytelling accomplishes both nicely. Also, when I read a blog post, I am not in a rush and don't want to feel like I should be.
I think the appropriate level of "storytelling" depends on the type of blog post. A "bug hunt" type of post is often told as a detective story. A benchmark post has almost zero storytelling. Different purposes warrant different approaches.
There's phone books worth of pages and text that never end up getting to the point.
I don't know if it's still there, but Grammarly used to have an AI feature that specifically made text longer. It was literally a button that says "Make longer."
>saying what you'll say, say it, then conclude by saying what you said.
In other words, the clearest possible conveyance of information.
At some point the learners have to connect with "why" and do something with the information. Is it the teacher's problem if students have no connection with the information they are being fed? It seems you would say no, let the students deal with the trouble of caring about and connecting to the content. You may be right.
I think it's not a strict binary question. Clearly some stages of learning require lots of information (grammatical and mathematical rules, for example). But stories often provide the hook or opening where the information starts to matter to the learners, and that holds for how I want my LLM to feed me information. This does not mean I want flowery and gratuitously validating prose for every scenario. My account-level instructions for chatgpt say something like "talk like Data from Star Trek." I've rolled my eyes more than once at the AI slop analogies or the overdone AI ted talk approach to everything.
When I explain something I think it's always useful to exercise at least a modicum of empathy towards my audience - I have learned far too many times that, thorough as my givings forth have been, my listeners have not understood things I assumed they did. That's where story comes in, and the right story connects to things students care about.
The twists and turns delays, and forward-looking tantalizers used to be for maximum impact once upon a time, and are still for that reason (or else for shits and giggles) on ad-free sites.
Today, the circumlocution is to keep you on the page or video for as long as possible for maximum monetization.
I actually disagree. We're humans and we love stories. They keep is engaged and are a good way to compact information. But it also is highly dependent on how it is done. Truth be told, we're constantly telling stories and I think part of the problem is not being cognizant of this.
> People want to save "twists" and "revelations" for maximum impact and it's harmful.
Maybe I'm misreading you. "Plot twists" would certainly be the wrong implementation. But when teaching one of my goals is to get students to be trying to ask a question that I'm about to answer. That's the story part. I'm leading them down the path and they should have suspicions about what lies around the next corner.
So basically a goal is that I'll stop for questions at some point and if I'm successful there'll be a student that asks a question we've been building up to and that I'm about to ask and/or answer. But there shouldn't be a "plot twist". I'm not trying to surprise students (usually :), but rather the story should make sense. As an educator[0] my goal is to get students to remember certain things and ask the right questions (a skill that's non-obvious yet people are overly confident about their level).
A good example of story driven writing is Cropper's The Quantum Physicists: And an Introduction to Their Physics. I really enjoyed this in my undergrad because it not only taught the physics but taught it in a historical manner. I said there's compression in story telling and this style of teaching did a great job at motivation of why these physicists were asking these questions. It gave context. I honestly think it had a big impact on me and helped push me into research (I do ML, not physics).
Certainly there's a time and place for being terse and hyper fixated on the information you're trying to teach but often we're trying to do a lot more than that.
FWIW, I think LLMs are terrible at this. They make everything seem "exciting". When everything is "load bearing" then nothing is. They're really bad at the context and understanding the bigger picture. They're especially terrible at responding to a question with something like "keep that question in mind, we'll come back to it in next week's lecture"
I think the list is great and hope to come back to this later in case I forget anything.
But! I don’t necessarily agree about the “overly formal” part—it definitely sounds good in theory but I don’t (personally) find the Author’s example formal at all. Moreover telling people to “write like they speak” is a good target but seems like a slippery slope, especially when many non-native English speakers (as one quick example) may blog in the language for larger reach or use it professionally.
I think it’s more important to avoid writing cliches and to use words as they’re intended e.g. a task might be challenging but it is not hard—a rock is hard.
"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.
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).
I would say these all boil down to empathy. Think about who your target audience is, and write for the least informed among them.
It’s ok to be selective about your target audience. Most of us are writing for free anyways so we’re not losing revenue by not explaining what a computer is in an article about optimizing LLM throughput. You might be writing to other engineers who are familiar with the topic but not the particulars of your project.
Put the most important thing above the fold. If you catch someone’s attention in the first 10 seconds, it buys you another 30.
Add visuals. Boxes and arrows, charts, videos where appropriate.
If you must write a meandering narrative, put it at the end, not the beginning.
Not just bloggers either. One look at the average YouTube video, and you'd think most people making those things had never heard the word 'brevity' in their life.
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.
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)
"Do this not that" lists are always contextual and situational. Some of this makes sense in the context of a professional or business site, but make sure your goals align before taking the advice.
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.
Many folks are great writers, but bad editors and the meandering intro is what kills most blog posts for me. Too bad because we really need more personal stories.
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.
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.
Actually in the beginning it tried to be a community but they forced it to be only an answer machine. They created and enforced a rule against anything outside of the strict Q&A format.
I don't see SO and software blog as interchangable things at all. SO is for seeking answers for specific problems, while blogs are for entertainment weaved with learning.
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.
From documents, and source code. I find it quite crazy that you imply that Stackoverflow is the sole information source for the SOTA LLMs. As a matter of fact, Opus 5.5 and Sol 5.6 both write acceptable zig code now and there are only ~400 questions about zig on SO. SO is just that obsolete.
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.
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.
I guess the author implies that a blog writer wants other people to engage with their articles. Without supplying any quantifiable evidence I wouldn't say I find it convincing, but I did stick around until the end of the article. That shows at the very least that the article was written in a way to keep me interested.
It comes down to your target audience. Everyone has preferences on what they read, someone who prefers formality might not enjoy casual blogs written how people talk. And vice versa. Software engineers in general probably prefer casual blogs, but there are software engineers that hold PhDs and prefer some rigor in the writing too.
This is by far the biggest challenge you'll encounter writing a tutorial, video game walkthrough, recipe, etc:
> “The reader knows everything I know except this one thing”
Because as the article says, it's hard to know what your audience already knows, and far too easy to take 'shortcuts' when helping them by forgetting how many things you've assigned to muscle memory.
Teaching people is difficult, and it's really easy to leave a lot of crucial information out if you're not careful.
That said, I do have one more antipattern (and one more recommended design pattern) worth considering here too.
For the antipattern, it's when the tutorial doesn't work anymore because of updates to the subject in question. I remember this being a big issue when I was trying to learn Angular a few years back, since the official tutorial was clearly written for a long obsolete version of the framework that functioned very differently from the current one.
The number of times I've had issues like that is far too high online, and it's usually because the person that wrote the tutorial didn't check back in on it whenever the language, framework or relevant dependencies got a major update.
So, if you write about a topic and things change significantly, go back and check your work from before. If you can, update the article, and if you can't, at least put a notice at the top saying the article is now obsolete and should be skipped.
On a different note, a good pattern to keep in mind is that you don't need to be chained to a specific format. Way too many people assume that because they're providing a written tutorial, there's no place for images or video content there.
But the truth is that in many cases, an image is literally worth a thousand words. In other cases, showing people how a step should go in video or GIF format can be more helpful than just providing a list of bullet points.
So, take that into account. Provide all the information in your chosen format for sure, but provide relevant images and videos when the info is clearer in that format, or for when people need a visual cue. That way, you can check them if you're struggling with the written instructions, and figure out whether your setup is wrong (or the tutorial has left out some crucial information) based on how similar the author's screen is to your own at that point.
Just because you're using text doesn't mean you have to treat your guide like it's going on GameFAQs in a .txt file in the mid 90s.
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."
Unless this is meant sarcastically, it sounds like an antipattern. If that’s truly the sole purpose of the first sentence, you might as well drop it and start with the second. The first sentence instead also should have a purpose of its own.
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.
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 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.)
Complete aside: I was reading about Jeff Bezos, who famously instituted required pre-reading at every meeting. That is, the meeting presenter prepared a 1-2 page paper on the context, goals, and proposed outcome of each meeting.
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.
Distract them by withholding information, so you feel like more of an expert than they are, and they don't have enough concrete info to form an attack plan.
An effective strategy for lots of higher tier management. For both good and bad reasons - often they don't want the details, they want to know that you know the details. You're being paid to know those details, after all.
As someone who has been interested in creating a blog in 2026, I still wonder what is the value of it in the age of LLM. No one is reading anymore… what do others think?
Curiously, over the past year I’ve found myself clicking through to read the article before the comments if the link looks like a personal blog. This is a huge change from how I used to peruse HN, which was checking the comments first, then the article if it looked interesting.
I read a lot of blogs in 2026. I often click the source links that LLMs provide so I can get more context, and to see what else the author might be writing about.
I haven't written on technical topics in a bit, but my goal is to write for the remaining community of humans who largely reject AI and still find value in actually thinking about things.
It does not matter how small this community is because, at least for me, it is the only engineering community that actually matters going forward.
I actually don’t like when technical blogging/writing is too casual, that’s distracting to me, the author isn’t my pal. It shouldn’t be excessively formal (as you’ve titled it) either, but neutral and matter-of-fact. For example, I enjoy Dijkstra’s writing style.
Yeah, I think a cool thing about blogging is that there are so many distinct tastes that there's a lot of room for different writing styles, and you can find people who like your style.
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 the biggest anti-pattern is not writing for who you are targeting, your intended audience.
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?
I fall into the camp where I agree with these antipatterns, so I'm probably not the target audience for the question. But a scenario could be if I was writing to appeal to PhDs or researchers, maybe I should include the links or citations on top of providing a brief summary of what a firewall is. Firewall might be a simpler example, but let's say a semi-novel algorithm for research sake.
My thinking there is PhDs/researchers a lot of the time like to dig deeper and are also pretty skeptical of new information and want to see it backed up by someone else unless the claims are completely novel, then they want the raw evidence typically in line or near what was stated as novel.
One could describe similar issues with video/youtube content. Everyone is engineering it for the algorithm but the thing humans want to know up front should be in the first 30 seconds.
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?
> 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?
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!
> 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 word, my whole blog is antipatterns (probably because I write it for me :D). Like, look at these doozies (all have lengthy preambles). There are more, but these cover all the antipatterns mtlynch mentioned. I am not at all sad, rather I am chuckling because when one doesn't care who reads the post, one can get away with such ghastly antimatter :D
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:
Over ten thousand ~~words~~ tokens on bitemporal data modeling (in SQLite and Clojure), which has a preamble and a postamble: https://www.evalapply.org/posts/poor-mans-time-oriented-data... (Plus, this one breaks on mobile portrait view because I couldn't figure out the CSS-fu needed to stop one pesky table from overflowing, and I am not going to fix it because the post reads fine in landscape mode).
A six part series, because this one got too long (re-making your dotemacs from scratch tends to go that way). Um, and each post gets progressively longer and preambly-er: https://www.evalapply.org/tags/emacs/index.html#main
Honest question: if you truly only write for yourself, why submit the posts to HN and prominently display social sharing shortcuts at the top of each post?
I can understand the position that you do care about other people reading your post, but you weigh 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.
Well, my site doesn't track views. No analytics etc. So I have no idea which post gets what traffic, and I very much prefer it that way.
Also, the posts are structured to the way I have come to arrive at some conclusion, or some understanding. So it is very much written for my own benefit, and incidentally shared because well why not. Surely I'm not the only one who was confused, or ignorant, or just curious about $Topic... Just don't expect that I will rewrite the thing for some abstract audience persona and how their brain works. If something is weird or unclear or plain wrong, search is at hand. And if something is annoying, well there are certainly lots of other places to go to instead. So, no, I don't really think about who reads my stuff. These days, it must be all bots anyway. So be it.
But I do like to also "learn generously", and I love to share and talk the about stuff I end up publishing from my drafts and notes (which far exceed the stuff up there in public view). So when I feel like it, I share links in various places. Usually its crickets. Sometimes there is conversation.
The "share to HN" etc. stuff is in service of prompting people to share if they feel so inclined. And honestly, I don't think people share via those links. No data, just gut feel, given how long the site has been up, and how uncommon it is for not-me people to post links to HN.
As for the prominence of said links. It has been an eyesore and a long-pending thing to delete. Sometimes I use the site as a playground. That time, I wanted to see if what "they" say is true about putting sharing links up top, prominently. So I slapped that section in, during one of the layout refactors.
And so, the top of the posts got way too busy with those "see me! pick me! choose me!" links, and stayed because I couldn't bring myself to refactor yet again. (Also because there's not much to lose because someone got annoyed at the eyesore click-share links. Yeah, friend, I'm annoyed too. Sucks to be us.)
Oh, I should add: "practise discussing things in public, without losing my cool" is also a reason I self-post links to forums like HN.
Not uncommonly, people are salty in the comments. Mostly it's fun to ignore the salt, and let the community do its thing, while also trying to observe what's going on with my feelings. Sometimes it's fun, or necessary, to show up and respond to flip the thread from destructive to constructive. This is a skill I can get better at, and I feel my odds of being better are higher with topics I've thought about for a good long while, and so that balances out in favour of taking the risk to self-share.
It so happens the eyesore "pick me!" links are gone now, except they are in a draft layout refactor. But please don't ask I know when it's going to go live. Could be tomorrow (or rather today---it's 2am here---and in that delicious sleep-deprived fugue state say eff this, I'm done, send it).
Well, you saved me writing a similar comment, and I like your blog too. (BTW I completely agree with your musings on what we might do with all this hardware, post-bubble. I actually started and... not quite abandoned a "sci-fi-ish short fiction" series on my own blog trying to think through those applications in my own industry.)
In my own writing it's like, I'm mostly trying to put something out in the world that I, and sometimes my friends, enjoy. The rambling is not exactly the point, but not exactly not the point either. If other like-minded people find it, great. Once somebody tipped me a thousandth of a Bitcoin or so, and that was fun too.
Hah, thank you for the kind appreciation. And I totally get that sentiment "the rambling is not exactly the point, but... ... ... ...".
For half a second I read the rest of it as "a thousand Bitcoin", and immediately thought "okay, so there's a story here about how it was way early and how you tipped someone else, and now, just look at them, wow".
It's because your blog is good. Not all blogs need to be primers targeted at idiot level leeches who abhor thinking for themselves and cry when confronted with facts like "the author is a different human than me".
Thanks for the compliment, but also wow the second part got salty fast!
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.
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.
it's always appropriate to share, but share your actual findings, don't imply or assume they are generalized maxims representing more than what it looked like to one guy doing one thing one time without a lot of experience.
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."
Great post, I am definitely guilty of overreliance on links. I need to get better about summarizing what I'm linking to to avoid a forest of homework to understand what I'm talking about.
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
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.
I think you are getting confused with the format for the reader. Someone looking for a light read would prefer a entertaining read with the twist of learning something, someone looking to learn something will be annoyed at your prose and narration style. What you write is aimed, whenever you like it or not, to a person in a particular state of mind. The motivated to learn will want you to not tell them about your grandma when they are reading the stupid recipe.
I think that's a factor as well. If the reader has a specific goal in mind, and your blog post presents itself as a way for the reader to satisfy their goal, then the reader will probably have less patience for stories.
But to take Spolsky's "Things You Should Never Do" as an example, obviously nobody's Googling, "things to never do," clicking Joel's article, and then getting annoyed at Joel for not telling them immediately. They're finding the post on HN, RSS readers, forums, etc., where they didn't have a specific goal in mind beyond learning/entertainment, so the author has more room to take their time.
I would argue that Joel and Paul's blogs are not education, they are opinion pieces. The fact that many of these opinions have become widely accepted over time doesn't change the format, which is that they are argumentative writing rather than purely informative (as you'd find in a textbook or scientific paper).
And this is exactly what the article fails to account for... they make several blanket assertions that may well make sense for certain types of posts but may not for others.
My 2c is that rule #0 of writing advice should be to take all writing advice with a grain of salt and an eye towards context and audience.
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)
With all due respect, PG and JS were titans of an era where attention spans were not short. I am not sure if that strategy would work in the LLM-era.
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?
Yeah, deciding on your assumptions about the audience's prior knowledge is one of the toughest parts of presenting information well, I think. If you give too much info, you come across as boring or patronizing; if you don't give enough info, most (if not all) of your audience will rapidly lose interest. But it's all gotta be based on your exact audience in the moment, and that's really hard to take into account a lot of the time.
When writing text, you have the advantage of being able to link to another text. In principle academic citations form a DAG that allows you to understand all prerequisite knowledge for any given paper. Your paper is expected to cite everything it depends on that isn't common knowledge but doesn't need to re-explain it.
> Yeah, deciding on your assumptions about the audience's prior knowledge is one of the toughest parts of presenting information well, I think.
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. Like some animals encountering an extremely realistic plastic fake that we cannot eat/mate-with.
Ooh yes, I like that way of framing the problem. I'll have to remember that!
Papers are written to peers. It shouldn't be a "murder mystery" for them (that doesn't mean it shouldn't tell a story). You have to write to your audience. If a paper was written to a general audience, instead of peers, every paper would have to be a novel.
I'll admit that sometimes I'm frustrated with HN comments on arxiv articles. Despite being a nerdy forum most papers aren't written for this audience. Hell, I have a PhD and most papers aren't written for me. Nor should they. I'm perfectly okay if I don't understand a paper. Arguably the hardest thing about a PhD is learning to be comfortable with being dumb and willing to work on becoming less dumb (you're never not dumb, only less dumb)
That's true, but I think scientific writing often veers too hard towards impenetrability. At least in machine learning, many of the hallmark papers are remarkably clear and simple in a way that most papers I read day-to-day aren't. Even something as simple as the problem setting can be written insightfully in a strong piece of work.
Honestly, I feel the opposite. But maybe that's because my doctorate is in ML. But we might also have a different definition of what the hallmark papers are. Many of the well known papers are ones that model scaled an existing method (ViT and ddpm are good examples). Important papers, but in which sense? I do think we have space for all types of papers and written to different audiences, but I don't think we should punish papers just because they're written to their niche domain. In the past decade there's been a huge increase in citation farming and I don't think that helps. Math is probably too much on one extreme but I think ML is on the other. You have to write your papers so a first year PhD can understand, because they're the ones reviewing your work. I don't think that's a desirable outcome
I was handed the paper: A rational design process, how and why to fake it [0]. It's still one of my favorit papers. Basically it tells you to, when writing documentation, go back and put in later findings in the place it would been, if the world had been completely rational. Just leave out all the weaving and late discovery, very few people cares. Retrofit documentation to pretend that everything and everyone was completely rational and had all the knowledge at the correct times. It can cut down documents by a lot.
0) https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...
My PhD advisor said something similar, but he also said papers tell a story. There are a lot of stories that aren't murder mysteries nor suspense novels. Your paper shouldn't be a novel and especially not a suspense one
Following the sequence of a-ha moments in a field is often a useful way to make them happen in the student: at first people thought things stopped after you pushed on them, but then Newton and Galileo realised this was because of a thing called friction, and if there wasn't any friction things wouldn't stop, and this means if you shift your perspective you can change how fast things moved. Later on Maxwell found his equations implied a speed of electromagnetic waves, such as light, but couldn't figure out what perspective it was in. Michelson and Morley tested it and strangely found it was true in all perspectives at once, Einstein made mathematical sense out of that which causes weird effects like time dilation, and our GPS satellites prove time dilation is true.
If I am reading a cookbook, tutorial, or reference to teach myself quickly so that I can accomplish something specific, I completely agree with you. Blog posts can teach something, of course, but when I choose to read a blog, I am hoping to experience a bit of the writer's personality and to be entertained in the process. Storytelling accomplishes both nicely. Also, when I read a blog post, I am not in a rush and don't want to feel like I should be.
I think the appropriate level of "storytelling" depends on the type of blog post. A "bug hunt" type of post is often told as a detective story. A benchmark post has almost zero storytelling. Different purposes warrant different approaches.
There's phone books worth of pages and text that never end up getting to the point.
I don't know if it's still there, but Grammarly used to have an AI feature that specifically made text longer. It was literally a button that says "Make longer."
>saying what you'll say, say it, then conclude by saying what you said.
In other words, the clearest possible conveyance of information.
At some point the learners have to connect with "why" and do something with the information. Is it the teacher's problem if students have no connection with the information they are being fed? It seems you would say no, let the students deal with the trouble of caring about and connecting to the content. You may be right.
I think it's not a strict binary question. Clearly some stages of learning require lots of information (grammatical and mathematical rules, for example). But stories often provide the hook or opening where the information starts to matter to the learners, and that holds for how I want my LLM to feed me information. This does not mean I want flowery and gratuitously validating prose for every scenario. My account-level instructions for chatgpt say something like "talk like Data from Star Trek." I've rolled my eyes more than once at the AI slop analogies or the overdone AI ted talk approach to everything.
When I explain something I think it's always useful to exercise at least a modicum of empathy towards my audience - I have learned far too many times that, thorough as my givings forth have been, my listeners have not understood things I assumed they did. That's where story comes in, and the right story connects to things students care about.
The twists and turns delays, and forward-looking tantalizers used to be for maximum impact once upon a time, and are still for that reason (or else for shits and giggles) on ad-free sites.
Today, the circumlocution is to keep you on the page or video for as long as possible for maximum monetization.
So basically a goal is that I'll stop for questions at some point and if I'm successful there'll be a student that asks a question we've been building up to and that I'm about to ask and/or answer. But there shouldn't be a "plot twist". I'm not trying to surprise students (usually :), but rather the story should make sense. As an educator[0] my goal is to get students to remember certain things and ask the right questions (a skill that's non-obvious yet people are overly confident about their level).
A good example of story driven writing is Cropper's The Quantum Physicists: And an Introduction to Their Physics. I really enjoyed this in my undergrad because it not only taught the physics but taught it in a historical manner. I said there's compression in story telling and this style of teaching did a great job at motivation of why these physicists were asking these questions. It gave context. I honestly think it had a big impact on me and helped push me into research (I do ML, not physics).
Certainly there's a time and place for being terse and hyper fixated on the information you're trying to teach but often we're trying to do a lot more than that.
FWIW, I think LLMs are terrible at this. They make everything seem "exciting". When everything is "load bearing" then nothing is. They're really bad at the context and understanding the bigger picture. They're especially terrible at responding to a question with something like "keep that question in mind, we'll come back to it in next week's lecture"
[0] I'm currently in industry
[1] https://archive.org/details/bwb_S0-BVP-068
In journalism this is called “burying the lead.”
In journalism it’s more commonly called “burying the lede”.
That’s basically an internet hoax.
I think the list is great and hope to come back to this later in case I forget anything. But! I don’t necessarily agree about the “overly formal” part—it definitely sounds good in theory but I don’t (personally) find the Author’s example formal at all. Moreover telling people to “write like they speak” is a good target but seems like a slippery slope, especially when many non-native English speakers (as one quick example) may blog in the language for larger reach or use it professionally.
I think it’s more important to avoid writing cliches and to use words as they’re intended e.g. a task might be challenging but it is not hard—a rock is hard.
Some weeks i feel like the majority of software blogs I see are LLM written now. They are usually terrible.
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.
> Maybe someone can tell the LLM's about these anti-patterns, like, seriously, would it help?
In a way, by posting this article online the author has already done that.
"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.
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).
i wonder how many of these are LLM-written.
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.
I would say these all boil down to empathy. Think about who your target audience is, and write for the least informed among them.
It’s ok to be selective about your target audience. Most of us are writing for free anyways so we’re not losing revenue by not explaining what a computer is in an article about optimizing LLM throughput. You might be writing to other engineers who are familiar with the topic but not the particulars of your project.
Put the most important thing above the fold. If you catch someone’s attention in the first 10 seconds, it buys you another 30.
Add visuals. Boxes and arrows, charts, videos where appropriate.
If you must write a meandering narrative, put it at the end, not the beginning.
"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.
Not just bloggers either. One look at the average YouTube video, and you'd think most people making those things had never heard the word 'brevity' in their life.
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.
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)
Then the better option would be to quote a paragraph for the impatient reader and provide a link to the source for further reading.
"Do this not that" lists are always contextual and situational. Some of this makes sense in the context of a professional or business site, but make sure your goals align before taking the advice.
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.
Many folks are great writers, but bad editors and the meandering intro is what kills most blog posts for me. Too bad because we really need more personal stories.
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.
[1] https://samkhawase.com/blog/email-is-crazy/
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.
Actually in the beginning it tried to be a community but they forced it to be only an answer machine. They created and enforced a rule against anything outside of the strict Q&A format.
I don't see SO and software blog as interchangable things at all. SO is for seeking answers for specific problems, while blogs are for entertainment weaved with learning.
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.
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?
From documents, and source code. I find it quite crazy that you imply that Stackoverflow is the sole information source for the SOTA LLMs. As a matter of fact, Opus 5.5 and Sol 5.6 both write acceptable zig code now and there are only ~400 questions about zig on SO. SO is just that obsolete.
They can read the web/repos just like anyone else.
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.
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?
yet AI companies scrape them constantly
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.
A blog is a journal of whatever the person wants. There isn’t an anti-pattern.
Not everything is a product.
I guess the author implies that a blog writer wants other people to engage with their articles. Without supplying any quantifiable evidence I wouldn't say I find it convincing, but I did stick around until the end of the article. That shows at the very least that the article was written in a way to keep me interested.
That’s like saying there is no such thing as bad writing because people can write what they want.
It comes down to your target audience. Everyone has preferences on what they read, someone who prefers formality might not enjoy casual blogs written how people talk. And vice versa. Software engineers in general probably prefer casual blogs, but there are software engineers that hold PhDs and prefer some rigor in the writing too.
This is by far the biggest challenge you'll encounter writing a tutorial, video game walkthrough, recipe, etc:
> “The reader knows everything I know except this one thing”
Because as the article says, it's hard to know what your audience already knows, and far too easy to take 'shortcuts' when helping them by forgetting how many things you've assigned to muscle memory.
Teaching people is difficult, and it's really easy to leave a lot of crucial information out if you're not careful.
That said, I do have one more antipattern (and one more recommended design pattern) worth considering here too.
For the antipattern, it's when the tutorial doesn't work anymore because of updates to the subject in question. I remember this being a big issue when I was trying to learn Angular a few years back, since the official tutorial was clearly written for a long obsolete version of the framework that functioned very differently from the current one.
The number of times I've had issues like that is far too high online, and it's usually because the person that wrote the tutorial didn't check back in on it whenever the language, framework or relevant dependencies got a major update.
So, if you write about a topic and things change significantly, go back and check your work from before. If you can, update the article, and if you can't, at least put a notice at the top saying the article is now obsolete and should be skipped.
On a different note, a good pattern to keep in mind is that you don't need to be chained to a specific format. Way too many people assume that because they're providing a written tutorial, there's no place for images or video content there.
But the truth is that in many cases, an image is literally worth a thousand words. In other cases, showing people how a step should go in video or GIF format can be more helpful than just providing a list of bullet points.
So, take that into account. Provide all the information in your chosen format for sure, but provide relevant images and videos when the info is clearer in that format, or for when people need a visual cue. That way, you can check them if you're struggling with the written instructions, and figure out whether your setup is wrong (or the tutorial has left out some crucial information) based on how similar the author's screen is to your own at that point.
Just because you're using text doesn't mean you have to treat your guide like it's going on GameFAQs in a .txt file in the mid 90s.
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)
Unless this is meant sarcastically, it sounds like an antipattern. If that’s truly the sole purpose of the first sentence, you might as well drop it and start with the second. The first sentence instead also should have a purpose of its own.
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.
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
Thanks for the reply.
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.)
"The 10 hottest new sentences about tech today. The sole purpose of sentence #7 will shock you."
Complete aside: I was reading about Jeff Bezos, who famously instituted required pre-reading at every meeting. That is, the meeting presenter prepared a 1-2 page paper on the context, goals, and proposed outcome of each meeting.
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.
Distract them by withholding information, so you feel like more of an expert than they are, and they don't have enough concrete info to form an attack plan.
An effective strategy for lots of higher tier management. For both good and bad reasons - often they don't want the details, they want to know that you know the details. You're being paid to know those details, after all.
All these anti-patterns are about me, but I have no intention of changing...
As someone who has been interested in creating a blog in 2026, I still wonder what is the value of it in the age of LLM. No one is reading anymore… what do others think?
Curiously, over the past year I’ve found myself clicking through to read the article before the comments if the link looks like a personal blog. This is a huge change from how I used to peruse HN, which was checking the comments first, then the article if it looked interesting.
I do! Usually I discover new blogs via Substack and read them via email client
Some responses (Simon Wilison, antirez, Gergely Orosz, Sean Goedecke...) here: https://writethatblog.substack.com/t/tech-blogger-insights?s...
IMO the value is in the thinking. Other people reading my non-professional writing sometimes the goal but most of the time it's a bonus.
People are still reading. At least I am :)
Much of the value of writing one goes to the writer!
I read a lot of blogs in 2026. I often click the source links that LLMs provide so I can get more context, and to see what else the author might be writing about.
I haven't written on technical topics in a bit, but my goal is to write for the remaining community of humans who largely reject AI and still find value in actually thinking about things.
It does not matter how small this community is because, at least for me, it is the only engineering community that actually matters going forward.
OP here.
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
I actually don’t like when technical blogging/writing is too casual, that’s distracting to me, the author isn’t my pal. It shouldn’t be excessively formal (as you’ve titled it) either, but neutral and matter-of-fact. For example, I enjoy Dijkstra’s writing style.
Yeah, I think a cool thing about blogging is that there are so many distinct tastes that there's a lot of room for different writing styles, and you can find people who like your style.
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.
Nice to see some Butterick fonts employed on a blog. ;) Mine’s the same, but I went with Valkyrie and Hermes Maia.
I think the biggest anti-pattern is not writing for who you are targeting, your intended audience.
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.
Thanks for reading!
> 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?
I fall into the camp where I agree with these antipatterns, so I'm probably not the target audience for the question. But a scenario could be if I was writing to appeal to PhDs or researchers, maybe I should include the links or citations on top of providing a brief summary of what a firewall is. Firewall might be a simpler example, but let's say a semi-novel algorithm for research sake.
My thinking there is PhDs/researchers a lot of the time like to dig deeper and are also pretty skeptical of new information and want to see it backed up by someone else unless the claims are completely novel, then they want the raw evidence typically in line or near what was stated as novel.
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! ;-)
One could describe similar issues with video/youtube content. Everyone is engineering it for the algorithm but the thing humans want to know up front should be in the first 30 seconds.
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
> 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?
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!
> 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.
I'll add one: Not including the date and time it was written.
My word, my whole blog is antipatterns (probably because I write it for me :D). Like, look at these doozies (all have lengthy preambles). There are more, but these cover all the antipatterns mtlynch mentioned. I am not at all sad, rather I am chuckling because when one doesn't care who reads the post, one can get away with such ghastly antimatter :D
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 :)
Over ten thousand ~~words~~ tokens on bitemporal data modeling (in SQLite and Clojure), which has a preamble and a postamble: https://www.evalapply.org/posts/poor-mans-time-oriented-data... (Plus, this one breaks on mobile portrait view because I couldn't figure out the CSS-fu needed to stop one pesky table from overflowing, and I am not going to fix it because the post reads fine in landscape mode). More thousands of words, urg no, tokens... on Terraforming one's infra: It opens with a Harvey Specter meme. https://www.evalapply.org/posts/systems-approach-to-infrastr... Another giant post on web stacks from first principles, and this one has a whole parable as well as a preamble: https://www.evalapply.org/posts/clojure-web-app-from-scratch... A six part series, because this one got too long (re-making your dotemacs from scratch tends to go that way). Um, and each post gets progressively longer and preambly-er: https://www.evalapply.org/tags/emacs/index.html#main(edit: reorder + fix formatting for clarity)
Honest question: if you truly only write for yourself, why submit the posts to HN and prominently display social sharing shortcuts at the top of each post?
I can understand the position that you do care about other people reading your post, but you weigh 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.
Well, my site doesn't track views. No analytics etc. So I have no idea which post gets what traffic, and I very much prefer it that way.
Also, the posts are structured to the way I have come to arrive at some conclusion, or some understanding. So it is very much written for my own benefit, and incidentally shared because well why not. Surely I'm not the only one who was confused, or ignorant, or just curious about $Topic... Just don't expect that I will rewrite the thing for some abstract audience persona and how their brain works. If something is weird or unclear or plain wrong, search is at hand. And if something is annoying, well there are certainly lots of other places to go to instead. So, no, I don't really think about who reads my stuff. These days, it must be all bots anyway. So be it.
But I do like to also "learn generously", and I love to share and talk the about stuff I end up publishing from my drafts and notes (which far exceed the stuff up there in public view). So when I feel like it, I share links in various places. Usually its crickets. Sometimes there is conversation.
The "share to HN" etc. stuff is in service of prompting people to share if they feel so inclined. And honestly, I don't think people share via those links. No data, just gut feel, given how long the site has been up, and how uncommon it is for not-me people to post links to HN.
As for the prominence of said links. It has been an eyesore and a long-pending thing to delete. Sometimes I use the site as a playground. That time, I wanted to see if what "they" say is true about putting sharing links up top, prominently. So I slapped that section in, during one of the layout refactors.
And so, the top of the posts got way too busy with those "see me! pick me! choose me!" links, and stayed because I couldn't bring myself to refactor yet again. (Also because there's not much to lose because someone got annoyed at the eyesore click-share links. Yeah, friend, I'm annoyed too. Sucks to be us.)
(edit: expand comment to clarify some thoughts)
Interesting, I appreciate the detailed response!
Oh, I should add: "practise discussing things in public, without losing my cool" is also a reason I self-post links to forums like HN.
Not uncommonly, people are salty in the comments. Mostly it's fun to ignore the salt, and let the community do its thing, while also trying to observe what's going on with my feelings. Sometimes it's fun, or necessary, to show up and respond to flip the thread from destructive to constructive. This is a skill I can get better at, and I feel my odds of being better are higher with topics I've thought about for a good long while, and so that balances out in favour of taking the risk to self-share.
Thanks :)
It so happens the eyesore "pick me!" links are gone now, except they are in a draft layout refactor. But please don't ask I know when it's going to go live. Could be tomorrow (or rather today---it's 2am here---and in that delicious sleep-deprived fugue state say eff this, I'm done, send it).
Or it could be next year.
(:
Well, you saved me writing a similar comment, and I like your blog too. (BTW I completely agree with your musings on what we might do with all this hardware, post-bubble. I actually started and... not quite abandoned a "sci-fi-ish short fiction" series on my own blog trying to think through those applications in my own industry.)
In my own writing it's like, I'm mostly trying to put something out in the world that I, and sometimes my friends, enjoy. The rambling is not exactly the point, but not exactly not the point either. If other like-minded people find it, great. Once somebody tipped me a thousandth of a Bitcoin or so, and that was fun too.
Hah, thank you for the kind appreciation. And I totally get that sentiment "the rambling is not exactly the point, but... ... ... ...".
For half a second I read the rest of it as "a thousand Bitcoin", and immediately thought "okay, so there's a story here about how it was way early and how you tipped someone else, and now, just look at them, wow".
(edit: also, cool blog yourself... subscribed!)
It's because your blog is good. Not all blogs need to be primers targeted at idiot level leeches who abhor thinking for themselves and cry when confronted with facts like "the author is a different human than me".
Thanks for the compliment, but also wow the second part got salty fast!
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.
35% readership on phones is disappointing when they make up 99% of end devices. Should I film a tiktok instead to get more audience?
Summary at the end is definitely an anti pattern too
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.
Nobody in this conversation is trying to discourage people from sharing their learnings. They are trying to encourage people to do it better.
> 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.
it's always appropriate to share, but share your actual findings, don't imply or assume they are generalized maxims representing more than what it looked like to one guy doing one thing one time without a lot of experience.
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."
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?
don't focus on the twists, no one cares
Great post, I am definitely guilty of overreliance on links. I need to get better about summarizing what I'm linking to to avoid a forest of homework to understand what I'm talking about.