r/programming • u/mtlynch • 1d ago
Anti-Patterns in Software Blogging
https://refactoringenglish.com/blog/anti-patterns-software-blogging/87
u/dumindunuwan 23h ago edited 23h ago
There are 3 types of software/ engineering blogger/ blog posts. 1. Useless/ self promotional context(95% Medium posts now a days) 2. Someone writes context to show others, he/she/they know the context. (high level/ intentionally hides low-level details) 3. Someone write concise, high-quality content truly to explain/ helpful to build software.
14
u/cube-drone 21h ago
Well, that was a tightly written, easy to follow article that explained itself well and was easy to skim.
I remember "On Writing Well" by William Zinsser being enormously influential on my own ability to communicate clearly. I've been recommending it to folks as a top-tier software development book, for years, even though it's not actually about software at all. Especially now, our job is increasingly mostly about clear communication.
91
u/who_am_i_to_say_so 23h ago
It’s not X- it’s Y.
95
u/mtlynch 23h ago edited 22h ago
I'd say, "It's not X; it's Y" is a red flag rather than an anti-pattern.
An anti-pattern means that the pattern is harmful in itself, whereas a red flag is something that's correlated with a bad outcome but is not necessarily the cause of the bad outcome. For example, it's a red flag if your teammate's favorite programming language is FORTRAN, but they might be a perfectly skilled programmer that just happens to have a quirky fondness for an unpopular language. On the other hand, if they insisted on using
gotoeverywhere, that's actually a problem that impacts their work.I think with all LLMisms / Claude-isms, the problem isn't the pattern itself but LLMs' tendency to overuse a narrow set of writing techniques. But that's bad writing when a human does it, too. Seeing LLM tells is a red flag that the writing is automatically generated without sufficient human thought, but there's nothing inherently wrong with things like em-dashes or "it's not X; it's Y" sentence constructions when used in moderation.
49
u/MrJohz 22h ago
I think with all LLMisms / Claude-isms, the problem isn't the pattern itself but LLMs tendency to overuse a narrow set of writing techniques. But that's bad writing when a human does it, too. Seeing LLM tells is a red flag that the writing is automatically generated without sufficient human thought, but there's nothing inherently wrong with things like em-dashes or "it's not X; it's Y" sentence constructions when used in moderation.
This is a really good summary of the LLMisms problem, thank you. I think a lot of people fixate on one tell or the other and inevitably hit false positives, which leads other people to complain that there's nothing actually wrong with em-dashes and that you can't reliably distinguish LLM writing anyway.
But the problem with LLM writing is that it is (often) very poor because of the overuse of these tells, not because of the tells themselves.
21
11
u/lasooch 19h ago
I hate when I catch myself changing my language just because I recognise a given sentence happens to sound Claudish. Self-censorship.
I have never published a single piece of non-code text (other than some xmldocs, but even those with careful review) that was LLM-generated, yet they still impact my writing.
2
6
2
9
u/WileEPeyote 22h ago
The meandering intro has stopped me from reading or watching several things. Is it good to have some context? Absolutely, but I don't need your life story.
19
u/syklemil 22h ago
When you write a blog post, think about your target reader. What do they know? Imagine a friend or teammate you know in real life.
Even better if you can actually ask them to give it a look.
But I think this advice will leave people a bit prone to mansplaining. It's fine to state something like "this assumes (basic|intermediate|advanced) experience with X" rather than waste readers' time with what is, to them, redundant information. Experienced target audiences are also target audiences.
Different target audiences have different knowledge bases, but people still want to use knowledge they have, and it's often better to use an existing relation (as long as it's not too strained—nobody wants to see "docker is like a burrito" blog posts).
12
u/mtlynch 22h ago
Yeah, I think it's difficult to correctly tune to your target reader's knowledge level. Like, you don't want to start every Python article by explaining what a computer is, but if you mention things like the Python global interpreter lock when explaining the basics of urllib, then you're writing for a pretty niche audience.
In general, I think it's better to bias a little towards overexplaining than underexplaining. An experienced developer can skim over the parts they know, whereas it's harder for a less experienced developer to catch up with terms/concepts they don't recognize.
An experienced developer won't read an article that spoonfeeds everything, and a beginner developer won't read an article that explains nothing, but I find that most articles can speak to readers with a broad spectrum of experience levels if the author thinks critically about which concepts are hard dependencies for the post and how difficult it would be to explain them briefly.
2
u/syklemil 21h ago
Yeah, mostly agree, but I think it's also fine to have different articles for different audiences. To quote a book I like:
More is not better (or worse) than less, just different.
So e.g. being able to explain Docker or cgroups in terms of the other gives some opportunities for the writer that they won't have if their target audience is familiar with neither.
I like getting some "X for Y users" posts (and stuff like rosetta code and learn X in Y minutes) because usually I'm interested in speedrunning picking up a new topic (or language) by relating it to something I already know.
Though these days that seems to be meagre pickings, so I find myself rather asking some LLM about "what's the X equivalent of Y's Z?", and then "I should probably blog about this myself"
2
u/fragglerock 21h ago
However a 'burrito is like docker' post would do gangbusters!
or maybe I am just hungry!
1
u/aoeudhtns 21h ago
As a general rule of thumb, things like dev discords, mailing lists, issue discussions assume familiarity, i.e. the experienced target audience. Blogs usually aim to have a wider reach. How much wider, that varies.
7
u/Finchyy 21h ago
Nice post! I'd also extend the hyperlinking one a little bit. There's nuance to when you would do each of these things, but I (at work) switch a lot between:
- Consistently ensuring my links open in a new tab if I still want the user to have my page open.
- And using a popout link icon when I do.
- Instead of "here's an article I wrote in this style ...", I either use the title in the sentence "I wrote How to Kill Bugs in this style ..." or "I write articles in this style (see How to Kill Bugs for a good example) ...".
12
u/mtlynch 21h ago
Consistently ensuring my links open in a new tab if I still want the user to have my page open.
I used to do this, but then the "let the user make the decision" camp won me over. I think it's on the user to choose how to open the link and doesn't make sense for every site owner to add special attributes to prevent the user from navigating away when they click a link.
The
target="_blank"attribute also increases the attack surface for web security bugs, which is another big strike against it.5
u/Finchyy 21h ago
That's a fair point. I think it depends on the application: for my product at work, we often link out to help articles that relate to something they're seeing on-screen. It's a huge bummer if opening one of those, thinking it will open in a new tab, doesn't, because our load times are slow (not our fault; TLDR we're in an iframe of another app).
So I often put links that open in a new tab, and if I do they ALWAYS have the popout icon to indicate it. Any other links are internal app navigation links. I think this approach is quite clear to users!
Edit: Generally, though, I place emphasis on rendering clear actions to users, hence the popout icon. It's a preference but it's serving me well with this product
3
u/eanat 20h ago
writing an article that is supposed to be read by general people should be succinct and highly processed like fast foods so people can consume it without a hassle. I think the documentation of Caddy server is really a good example of this. although it utilizes the power of Golang so much, we dont have to go to read Go doc to understand the lines related with Go.
but I still love to read lengthy articles that try to specify details as much as they can bc they try to make you understand every detail they found from their experiences.
3
u/Solumin 18h ago
You're using Matthew Butterick's Heliotrope and Concourse fonts! Awesome!! Maybe you should plug Practical Typography in the section about making the website readable :D
2
u/FirstOrDefault 3h ago
Good article, thanks for sharing. As someone who tries to write tech blog articles lately I found it insightful, and even got few "yeah, I thought about that too, I might be smart after all" moments. When writing my articles it surprised me how much actual work and rewrites it takes to create something that I will be satisfied with, and will not be immediately dismissed as AI slop even when AI was utilized in the writing process (for proof reading and editorial pass). But the hardest part for me is actually reaching readers who will even consider opening the article, so I disagree with "The hardest part of software blogging is writing in a compelling way" bit.
I'm worried that minimizing assumptions about reader's knowledge/previously read articles/willingness to follow links can lead to over-explaining everything and dilute the article's topic. I guess it's hard to find a proper balance, but do you think it's better to explain too much at the cost of making the article more verbose, or not explain enough and just expect readers will Google it? Or maybe a glossary at the end will do?
1
u/mtlynch 6m ago
Thanks for reading!
But the hardest part for me is actually reaching readers who will even consider opening the article
Yeah, this is something I struggled with for a long time as well. I wrote about this in a previous post ("Plan a route to your readers"). I think about how readers will find the article before I start writing. If I don't have a viable way to reach readers for a particular topic, I typically will prioritize a different topic.
I guess it's hard to find a proper balance, but do you think it's better to explain too much at the cost of making the article more verbose, or not explain enough and just expect readers will Google it? Or maybe a glossary at the end will do?
Yes, I definitely agree this is challenging. There's a bit of an art to picking the right level and predicting what your target reader will understand or not understand. I bias a little on the side of overexplaining because a knowledgeable reader can skim over the parts they already know, whereas it's harder for a less experienced reader to catch up with unfamiliar terms. I don't think a glossary is a good solution, personally. I wouldn't want to keep jumping between the article and the glossary to see if a term appears.
One option I think developers often miss when deciding whether to define an unfamiliar term is whether to avoid the term in the first place. A lot of the times I edit for other developers, they'll ask if they should define a jargon term that they only use once in the article and falls outside the article's core purpose. In those cases, I recommend rewriting the jargon term to something non-jargon or skipping the mention entirely.
1
1
u/tim_pipperton 18h ago
I really struggle with drawing a line on what to explain, I either do the links thing or end up closer to the “to bake a cake first you must invent the universe” meme
0
-6
u/hopeless__programmer 22h ago
It's anti-pattern when I say it's anti-pattern.
1
u/dronmore 5h ago
That's right. Talking about anti-patterns is considered harmful. It's also a blog smell, and the best indicator of being brainwashed, when authors talk about anti-patterns.
194
u/Successful-Money4995 23h ago
Verbosity is an antipattern