Stop Meandering: The Biggest Mistake in Software Blogging

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.

"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 ne […]

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.

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.