Anti-Patterns in Software Blogging(refactoringenglish.com) |
Anti-Patterns in Software Blogging(refactoringenglish.com) |
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.
A lot of Paul Graham and Joel Spolsky posts don't get straight to the point and usually do not follow an intro -> body -> conclusion format. A lot of them start with a story that makes the direction of the post unclear[0] or include long digressions whose value isn't immediately obvious.[1]
For a while, I struggled with this contradiction because I think good writing should quickly demonstrate the value a reader can expect, but I think Graham and Spolsky are excellent writers that frequently take their time in getting to their point.
The easy answer is that Graham and Spolsky are famous, so they can do whatever they want, and people will still read. I've come to think it's actually that writers like Graham and Spolsky are so good that the quality of the writing itself is the thing of value that keeps you interested even if you don't know what point they're going to make.
[0] https://www.joelonsoftware.com/2000/04/06/things-you-should-...
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)
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.
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.
But also in the case where the writing is actually not technical, then... obviously the parent comment's complaint wouldn't apply? C'mon.
It is a massive turn off for me and I just simply close the window if I find they don't get start getting to the point.
I am much more forgiving if the meandering intro is done by someone that is clearly just someone writing up their own work.
Anyway, I'm learning so much more so much better than I ever have before. Turns out the ultimate slop tools are also the ultimate learning tools if you use 'em right.
People are not using it any more as any AI assistant will give you the answer in seconds, perfectly adapted to your use case and with an easy way to ask follow up questions.
StackOverflow was always just an "answer machine".
They wanted it to be a community, but it never was.
"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)
Or write something that actually provides value to your reader, communicate that value effectively, and trust your reader to recognize that value. Which would you rather read: writing that was optimized for psychologically capturing your eyeballs, or writing that was optimized for providing you something of value?
If you click on a blog post, and the writing is poor or seems LLM-generated, you keep reading? Or do you mean that you're willing to forgive more superficial things like meandering or excessive formality if the post has other redeeming qualities?
As an example, I clicked a post a few weeks ago about orchestrating Claude Code sessions[1], as that's a topic I'm interested in, but I found the writing so poor that I felt like the post was either LLM-generated or written for someone who had different needs than I did. Would you read a post like that to completion if the topic interests you?
[0] https://lobste.rs/s/youq7y/how_write_blog_posts_developers_r...
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
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.
This is something I see a lot too, and I almost covered it in the post. I think it goes hand in hand with excessive formality where people think that if you're writing a blog post about something, you have to be an authority on the topic, but that's not true.
It's valuable and useful to write about things when you're still a beginner as long as you present yourself as a beginner. Julia Evans does this extremely well. My favorite example is "Some notes on using nix,"[0] which got me to start using Nix when I'd seen lots of other posts from more experienced Nix users that were too in the weeds for me to understand. But the way Julia approaches it is that she's learned a little bit more than someone who's never touched it, so you can read her progress and get a slight head start from where you would have started without her notes.
[0] https://jvns.ca/blog/2023/02/28/some-notes-on-using-nix/
Yep, I agree with this.