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.

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.

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" might be the most common mistake, by far, but the most damaging mistake, by far, is the failure to connect the topic with something the readers are familiar with (anti-pattern #2). Some things simply require a certain level of expertise/prerequisites to begin to understand, but I've repeatedly seen in software blogging, READMEs, etc. a failure to answer "what is this, compared to what I'm familiar with, and if I'm not familiar with anything relevant, why should I want to be?"

This applies to almost everything in the software space. New tool? New design pattern? New library? Language idiom? Language? Or, for more modern takes, new model? New harness? New harness option? New use pattern? Give a brief summary of what a project looks like without it, to convey the problem that its existence alone is solving. Then go into the details of how it might compare to other solutions.

Maybe it's just a specific way of how my brain works that finds this sort of information intuitive, and the lack of it particularly annoying.

This is 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.

Last week, after following an HN link, I found myself thinking that tech blogs were starting to need that "Jump to Recipe" link that has taken over the food blogging world (for the better).

"The meandering intro"

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.

"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.

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)

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/

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.

The community yearns for a new stack overflow.

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)

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?

A blog is a journal of whatever the person wants. There isn’t an anti-pattern.

Not everything is a product.

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.

Summary at the end is definitely an anti pattern too

OP here.

Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.

I'll add one: Not including the date and time it was written.

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.

> 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:

  Exhibit B:

  Exhibit C:

  Exhibit D:

(edit: reorder + fix formatting for clarity)

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".

don't focus on the twists, no one cares

Helpful, thank you. I'm just going to write such an article

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.