HN

Comments (65)

• Menu

  phreack
  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.
• jrochkind1
  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.
• ram1500natrluvr
  "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.
• Menu

  linsomniac
  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).
• mattbrewsbytes
  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.
• Menu

  weinzierl
  "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.
• kkapelon
  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)
• FlyingSnake
  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/
• Menu

  mobilejdral
  The community yearns for a new stack overflow.
• Menu

  joshkel
  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)
• Menu

  0x20cowboy
  A blog is a journal of whatever the person wants. There isn’t an anti-pattern.Not everything is a product.
• Menu

  xpct
  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.
• mexicocitinluez
  I'll add one: Not including the date and time it was written.
• Menu

  mtlynch
  OP here.Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
• ramon156
  don't focus on the twists, no one cares
• rglullis
  > 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.
• totallygeeky
  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.
• Menu

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

  mcphage
  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".
• sophietaylor
  [flagged]
• arpanghoshal
  [dead]