News for hackers. Stuff that matters.
Re:Ask HN: What makes you want to keep on reading README? by smoldesu on Tuesday March 22, 2022 @05:49PM (#30772013)
Screenshots are a great start.

Close second is formatting: I really like projects that start with the hook (usually an image of the software in use or an "elevator pitch" of what it's trying to solve), follows up with a list of features, capabilities or FAQ, and then finishes with the less salient info like contribution instructions, build instructions, and general how-tos.

I think upfront it's worth noting that you probably don't need people to "keep on reading" your entire README, in an ideal world you're able to convey the important details first and address more granular issues in a structured and easy-to-parse way. YMMV, but that's my two cents.

Re:Ask HN: What makes you want to keep on reading README? by smoochy on Tuesday March 22, 2022 @05:52PM (#30772044)
So, obviously, I think formatting (even if we talk about plaintext that isn't modified) is important and I do think a screenshot and maybe a short screencast - those are all important things. But suppose you couldn't display images or even link to them. How does one find the right words? I guess that's my question, yes. Words.