←back to thread

How to write blog posts that developers read

(refactoringenglish.com)
595 points rbanffy | 3 comments | 28 Mar 25 11:01 UTC | HN request time: 0.515s | source
Show context
dynm ◴[28 Mar 25 15:50 UTC] No.43506902[source]▶
I reckon if you wanted to choose just a single rule it should be, "Write something that you yourself would actually read." The problem is that our brains are designed to sort of lie to us and tell us that what we've created is amazing when in fact we'd never actually read it if someone else had written it. If you can find a way to be objective and see your own writing as the far-from-perfect mess it actually is.

(In principle, you could use "write something that someone else would actually read", but I think this is much harder, because it's much harder to know how other people would react! If you yourself would read it, well, we aren't that unique, lots of other people would read it too.)

Also, props for this stark picture of reality: https://refactoringenglish.com/chapters/write-blog-posts-dev...

replies(4): >>43507521 #>>43508276 #>>43508883 #>>43513537 #
1. kqr ◴[28 Mar 25 19:02 UTC] No.43508883[source]▶
> I reckon if you wanted to choose just a single rule it should be, "Write something that you yourself would actually read."

This is a good rule, and I think the first test of it is "have you suffered through proof-reading it three times?"

The garbage people write when they don't even proof-read it themselves! I find that by the third time I read through my writing (ideally spaced out over a few days) I have worked out most of its kinks.

And read it out loud! If you cannot, at least get an AI voice actor to read it for you. You catch so many more problems that way.

replies(2): >>43509187 #>>43509404 #
2. mtlynch ◴[28 Mar 25 19:37 UTC] No.43509187[source]▶
>And read it out loud! If you cannot, at least get an AI voice actor to read it for you. You catch so many more problems that way.

Definitely agree.

I initially included this in the article but I took it out because I wanted to limit to just advice I didn't see covered much elsewhere, but I always tell people to read their writing aloud.

I don't think an AI voice would get most of the benefits, though. For me, a lot of what I notice when I read my writing aloud is that I find myself naturally finishing sentences in a way that departs from what's on the page. And however I finished the sentence naturally almost always is a better rewrite than what was originally there.

3. bluGill ◴[28 Mar 25 20:07 UTC] No.43509404[source]▶
That is always what I hate about discussions like on HN, reddit, and the like: if you don't respond "fast" nobody will read it. By rights instead of hitting the reply button in a couple minutes I should put this reply in some queue, and review it several times over several times and then hit reply. However that means my insightful (lets assume insightful, though that isn't always a given) reply has waited until this is well off the front page and so nobody (except maybe the person I'm replying to) will notice.

Instead what I do is glance over things - but that mostly means I fix anything my spell checker has flagged. I know from experience that if less than several hours haven't passed I will not see all the things that don't make sense - they make sense in my mind and I know what I meant really meant. Several hours/days later I will see just how impossible things are to understand. (I'm now going to press that reply button, I hope this all makes sense to you..)