How to write blog posts that developers read

(refactoringenglish.com)

Show context

marginalia_nu ◴[28 Mar 25 14:01 UTC] No.43505551[source]▶

My general takes (as someone who also has a somewhat popular blog) is that

The inverted pyramid is almost always the correct format for your text. I often put the tweet-length version of the post in the title or first paragraph. Get to the point quickly, then elaborate. Means you can bail out at any point of the text and still take home most of what mattered, while the meticulous crowd can have their nitpicks addressed toward the end.

The problem of finding an audience is best solved by being really transparent about what you're about. Inverted pyramid solves that. There's no point to drawing in people who aren't going to be interested. Retaining existing readers beats capturing new readers.

I'm less bullish on images, unless they are profoundly relevant to the text. Illustrations for the sake of having illustrations are no bueno in my opinion. You want to reduce distractions and visual noise. Images should above all never be funny.

replies(15): >>43505573 #>>43505719 #>>43506046 #>>43506189 #>>43506400 #>>43506970 #>>43507372 #>>43507727 #>>43508468 #>>43508865 #>>43508960 #>>43513506 #>>43514694 #>>43515583 #>>43516620 #

mtlynch ◴[28 Mar 25 14:16 UTC] No.43505719[source]▶

>>43505551 #

Thanks for reading, Viktor!

>I'm less bullish on images, unless they are profoundly relevant to the text. Illustrations for the sake of having illustrations are no bueno in my opinion. You want to reduce distractions and visual noise.

I'll respectfully disagree on this one. You can overdo images, but I think readers find a wall of text intimidating and visually too boring, but this is a matter of taste.

>Images should above all never be funny.

I strongly disagree with this. It's like saying a technical blog post should never have jokes.

Why should an image never be funny?

I think you absolutely can mix humor and useful technical insights. xkcd is probably the best example, but there are lots of authors that complement their writing with humor, both in images and in text.

replies(2): >>43505833 #>>43506017 #

1. marginalia_nu ◴[28 Mar 25 14:24 UTC] No.43505833[source]▶

>>43505719 #

I think you can be funny, but only in posts that are made to be funny. xkcd is primarily intended as comedy and that's fine.

Mixing humor into serious communication comes at the expense of authenticity. It's difficult to know what an author really means when they mix attempts at humor into the writing (and this is often deliberate, if someone makes a particularly spicy political remark, it's usually in the form of a joke, in order to shield from potential backlash). Overall it's a style of writing that feels sophomoric and insecure, as though the message itself isn't enough so there's a need to crack jokes to compensate. This successfully distracts from the message you're trying to convey, ... at the expense of clarity.

replies(3): >>43505902 #>>43513546 #>>43515999 #

2. lapcat ◴[28 Mar 25 14:30 UTC] No.43505902[source]▶

>>43505833 (TP) #

> Mixing humor into serious communication comes at the expense of authenticity.

Only if you're authentically humorless. ;-)

replies(1): >>43505949 #

3. marginalia_nu ◴[28 Mar 25 14:34 UTC] No.43505949[source]▶

>>43505902 #

I wouldn't say never under any circumstance to do this, a pun or a joke occasionally creeps into my posts as well, though I feel this is definitely a less-is-more thing.

You sometimes find texts where you get the feeling the author almost expects a sitcom laugh track over the post, and funnies are crammed into every available crevice.

replies(1): >>43506263 #

4. lapcat ◴[28 Mar 25 14:57 UTC] No.43506263{3}[source]▶

>>43505949 #

To put it in perspective, I would note that the article title specifies "how to write blog posts", plural, not merely "how to write a blog post", singular. In other words, you're promoting a body of work, or for lack a better term, a "brand". If you want your brand to be authentic, it needs to reflect your personality. Thus, I think there is leeway for humor, even sarcasm, meandering, rambling, if that's what you tend to do. If you can establish a brand, an audience, then readers will stay with your blog posts because they were written by you, in spite of your style, or perhaps due to your style. Ultimately, of course, you need something interesting and/or important to say, but you don't need to present it robotically. Unless you are a robot! The negative oneth law of robotics is that a robot must not attempt humor.

5. n0tquitehere ◴[29 Mar 25 07:28 UTC] No.43513546[source]▶

>>43505833 (TP) #

Humour can absolutely feel forced and insecure, however it can be a great tool to help deliver a point. Done well humour can help with the flow of a presentation or text, done badly it jars. You have to know your audience and keep your humour on topic: "street jokes"* are almost never going to work in your favour.

I read a really interesting book* about the topic a while back where the authors delve into why humour works and how to find a style of humour that works for you. Unfortunately there are places imo where they fall into their own trap of trying too hard, but honestly it serves to prove the point.

* https://www.urbandictionary.com/define.php?term=Street%20Jok...

* https://www.humorseriously.com/

6. ThrowawayR2 ◴[29 Mar 25 14:48 UTC] No.43515999[source]▶

>>43505833 (TP) #

Steve Yegge's (in)famous Google platforms rant and his other early essays is a counterexample I would think. It was taken down long ago but there's an archived copy at https://gist.github.com/chitchcock/1281611 .

↑