How to write blog posts that developers read

> Images should above all never be funny.

Why on Earth not? Maybe a blog about conflict in the middle east isn't the place, but a blog sharing stories about the tech industry? Surely some humorous screenshots will add to the experience.

Obviously just throwing in random images totally unrelated to the subject matter would be a huge turnoff, but I cannot think of any reason why you'd take such an absolute position on something so low-stakes.

You get this jarring tonal whiplash when you add funny images to an otherwise serious text. The images detract from the message you are trying to convey. It also risks triggering a skimming behavior where the reader is just skipping between the images.

It also appears insecure and juvenile, as though you're not fully confident that what you are saying will stand on its own without attempts at comedy, and ironically raises questions about the age and experience of the author.

Of course there are exceptions, but as a rule of thumb, I would strongly avoid this pattern of communication.

You're kind of moving the goalposts.

You went from "Images should above all never be funny," to "You get this jarring tonal whiplash when you add funny images to an otherwise serious text."

Yeah, if a post's text is 100% serious, then yes it would be jarring to insert funny images. Nobody's suggesting you do that, though.

>It also appears insecure and juvenile, as though you're not fully confident that what you are saying will stand on its own without attempts at comedy, and ironically raises questions about the age and experience of the author.

This comes across to me as strangely judgmental and narrow-minded about what good technical writing is.

Joel Spolsky is, in my opinion, the best software blogger of all time. His posts often integrated humor, and I think it definitely heightened rather than detracted from his writing.

Look at the bloggers who are most popular on HN: Paul Graham, Julia Evans, Simon Willison, Rachel Kroll, Terence Eden. All of them often use a lighthearted style and integrate humor, often with humorous images as well.

it decreases authority projection

I agree with the point and didn't realise it until I read this post. Whenever I see a funny image or comic in a technical post it always feels a bit like it doesn't quite belong there, like someone had a quota for humour. It feels a bit like the author isn't confident with their message and acted like a conference speaker throwing in a bad joke for some easy laughs.

It also breaks the flow. Reading from long form text and then skipping to image and parsing the text breaks the mental flow, for me at least, and there never seems to be a clean place to do it.

It sounds like your problem isn't with funny images, but tonal mismatch. In that sense I agree with you - if the article's tone is lighthearted, use lighthearted images. If not, then don't.

I would expect the "a monad is just a monoid in the category of endofunctors, what's the problem" article to include humorous images. I would expect a serious tutorial about monads to not do so.

I think the key is to be your authentic self. If you’re trying to force being funny it comes off poorly.