Anti-Patterns in Software Blogging

Sure; your time is yours, use it how you like!

"Overreliance on links" makes me sad. I love linking to things. I have a suspicion that nobody on the internet clicks links any more, if they ever did.

I think we probably agree on how to use links.

I link heavily too, so I don't think there's anything wrong with linking itself. My rule of thumb is that my article should still make sense to the reader even if they don't click any links. That's the sense I get when I read your blog too. You offer links so the reader can dig deeper, but you don't expect the reader to stop and read every link.

Yeah the inverted pyramid is pretty much the template for all my technical blog posts. Very rarely goes wrong.

"Overreliance on links" makes me sad. I love linking to things. I have a suspicion that nobody on the internet clicks links any more, if they ever did.

I generally find websites in general tend to not link nearly enough. There's a crap ton of websites with nearly no outbound links what so ever, I think in some misguided attempt to keep the visitor from leaving.

Though link-rot is a legitimate concern and a pretty big problem, but I don't think not linking is the answer.

"Drop the formality. Write the way you speak in real life." - 100% agree. You have a voice, use it!

I don't speak the same way to everyone in every situation, that would be weird. Formal language doesn't have to lack a voice, though it demands familiarity with that writing style to shine through.

I think "reliance" is the keyword. As @mtlynch & @JulianSildenLanglo commented below, the references shouldn't be required reading to continue. Otherwise, the reading experience feels like a async runtime, switching tasks at every "await" (hyperlink)!

I have a suspicion that nobody on the internet clicks links any more, if they ever did.

I click links. I love them. Maybe a bit too much though, since I tend to fall into recursive reading.

Sort out your headers and tags: Setting up preload / preconnect / defer, and navigation hints are a low and one-time time cost to making your site feel snappier without having to really change anything about your content.

Few blogging sites should benefit from these things. Preconnect? You should only be loading first-party resources, and if you’re doing something like analytics on another origin, you don’t want to prioritise that. Preload? Simplifying very slightly and with the possible exception of web fonts, if inserting such things manually makes a difference, you were doing the wrong thing. (The sorts of sites with piles of chunked JavaScript that may benefit from it use build systems that generate that.) Defer? Honestly it’s almost never what you actually want, you typically want <script> or <script async>.

Setting the lang attribute on your top level is also a cheap win for better hyphenation

I don’t believe any user agent stylesheets hyphenate by default, and I don’t think your stylesheet should enable it either. My vague feeling is that consensus has steadily been creeping up that hyphenation is just a bad idea in general, along with justifying prose on any but very narrow columns like newsprint.

But do still make sure lang is correct.

Minimize assumptions about the reader’s background knowledge.

A better way to say this is: "know your audience and their background knowledge."

Always assuming the reader is a total beginner also doesn't lead to the best writing.

This is a good post all around! I agree with most points, but I also think it's incomplete without saying that there are exceptions to some of these rules, and you can execute them pretty well! For example:

1. The meandering intro: you always want readers to want to read your post. But there are ways to do that other than matter-of-fact statements and clickbait. For example, some people might follow you for your personality, because they're interested in what you're doing. Unique styles, well-designed pages that catch attention at first glance, or just being vaguely prominent can give you such an audience. Of course, this most often only works for existing readers, so you might want to use different styles in different posts.

2. The reader knows everything I know except this one thing: you do want to minimize the number of unnecessarily referenced complex topics, but if you overdo it, you just won't have anything useful to say. There's no good way explain how Docker works internally to someone who doesn't understand how Linux works, or to write a post on newly proposed Rust features to someone who never touched type theory. So when this post says "minimize assumptions about your reader", that doesn't mean to write for the lowest common denominator, it means choosing your intended audience deliberately. And it's fine if you want to keep the content deeply technical, we need that too!

3. The sequel injection bug: I think Raymond Chen makes this work. Many of his posts link to a previous post in the first paragraph, and that paragraph is a summary of that post. As in, the entire paragraph is a link, or at least a large part of it is. This feels quite intuitive, and I think it works because there is no textual hinting to read the prequel. Also, if you want to refer to a previous post that is only loosely related (e.g. it covers a different feature that you've worked on in the same project), don't make it feel like a prequel, just treat it like any other link and you can keep it.

One of my favorite tricks: chop the entire first paragraph and see if the post is still readable. If it is, it’s probably better off that way. Then repeat!

Always felt weird about the style of blogs I write, so the reassurance that you can chill out is refreshing. Do you have any tips on creating/thinking about the list of things your reader might know // how you'd determine who your reader is likely to be?

I think making your blog require JavaScript is a pretty good indicator you aren’t hitting your target audience of technical readers. Many of us come in on browsers without JavaScript or JavaScript in allowlist mode since the internet is full of hostile nonsense—so why would I assume a random blog also isn’t in this category (or at least have the courtesy to show a <noscript> that explains what’s actually being missed)?

i was recently rewatching the classic sandi metz talk all the little things and there's a moment where she drops "duplication is far cheaper than the wrong abstraction" and says

the first rule we teach novices is "don't repeat yourself"—DRY but have you ever thought about why we teach them that rule? it's because they can't understand anything else. they don't know anything! but by god, they can recognize duplication! and it's a good rule! i'm not saying it's a bad rule. but now you've grown up, you know more, you have enough experience to tolerate a little duplication and wait on a better abstraction.

one of the biggest "media engagement hacks" is to generate a Take so atomic that your income is powered through the sheer number of clapbacks it generates. if that's your goal, so be it. but i think that as a writer, blogger, whatever you think of yourself, you are allowed to write however you want, to formulate your thoughts as you see fit, to use excessive links, or to be flowery in your prose, to make assumptions about your audience, or design your page however. we have so many spaces where the code we write or emails we send or takes we have must fit within the confines of some extant style guide or database column, but my claim is that your blog is your space to be yourself and there's nothing forcing you to write a blog "that performs well."

as you write more, you'll find what works to best communicate your thoughts and what doesn't, there is no one-size-fits-all set of edicts or prescriptions. thinking of anti-patterns in tech writing, i think the biggest one is transitioning from a person who writes about topics in tech that interest them, to becoming a person who hunts around for topics they think others will be interested in reading about. the former is a hobby, the latter is jobbing.

the farthest extreme of software blogging is writing about other people's writing in order to market your non-software content. there's no wrong place to be on the spectrum of hobby to professional blogger, but i find that people who vocally prescribe rules for others, be it in fashion, writing, art, or other avenues of self expression have lost sight of where they have ended up. for the rest of us, it is good to remember that we're grown ups, we know more, and we have enough experience to gradually develop our own practice in a way that enriches us best.

I had a large answer written, but Joel Spolsky had already a better answer to a similar kind of statement 26 years ago:

Jakob Nielsen says that Flash is “99% bad.” I have to agree. Flash always reduces usability.

On the other hand, every time I read Jakob Nielsen, I get this feeling that he really doesn’t appreciate that usability is not the most important thing on earth. Sure, usability is important (I wrote a whole book about it). But it is simply not everyone’s number one priority, nor should it be. You get the feeling that if Mr Nielsen designed a singles bar, it would be well lit, clean, with giant menus printed in Arial 14 point, and you’d never have to wait to get a drink. But nobody would go there, they would all be at Coyote Ugly Saloon pouring beer on each other.

https://www.joelonsoftware.com/2000/11/02/20001102/

The only rule, if you ask me: if it is your blog, you write for you. Do what you like.

I want to offer the additional perspective that technical people can simply tell stories that may contain technical content. Posts don't have to have learnings (any more than any good story does) or provide "fish on a plate".

I think of Rachel by the Bay. Or The DailyWTF as two examples of technical blogs that I think violate these patterns to good effect (though The DailyWTF has its own large meta-discourse about what makes a good post).

I want good technical content like these anti-patterns warn for AND I want more people to just try to tell some stories.

While people may complain about meandering introductions, they are usually (as in the example provided,) sufficiently visually distinct that it's easy to skip over them. All this costs anyone is a little scroll.

However, asking authors to reïntroduce basic knowledge throughout, this tends to be mixed in with every paragraph, and it's much harder to skip. In fact, since many complex concepts require extensive background knowledge, the amount of space dedicated to “minimi[sing] assumptions about the reader's background knowledge” may rival that needed to describe the author's contributions to the topic. There is some sleight-of-hand in the example the author uses, but I can see where a reader may actually prefer the contraïndicated version, which is more interesting and has more “texture” than the alternative (which is bland, boring, and, in this case, misleading.)

Adding a link to shirk explication of some critical detail—sure, that's no good—but if the purpose of the post is to convey factual information, it seems like external (primary) sources are a critical piece. Again, I don't think the examples here really illustrate the point the author is trying to make, as the link is not particularly useful in either case, since it provides no practical supporting or corroborating information.

Honestly, I think the best modern advice is for authors is: if you need to be told this, then you shouldn't use an LLM to aid in your writing in any capacity. (If you didn't need to be told this, then you probably already knew how to use an LLM responsibly, and are at low risk of turning your writing into mushy goop.)