Ask HN: What makes you want to keep on reading README? | Hacker News Reader

Ask HN: What makes you want to keep on reading README?

6 pointssmoochy4 comments

When you visit some new or not so new open-source project's page, whether it's on Github or maybe it has some sort of website, what makes you want to keep on reading after you glanced over the title and the first paragraph of text?

I would like to specify that I only mean content here - not presentation. So imagine there's just plaintext and browsers are not capable of displaying anything else but it.

Of course we all know that a well written documentation in general is such a rarity in this world and there are, in truth, very few examples (FreeBSD comes to mind) of documentations that stand out simply because you can sense every single sentence was written by a human passionate about it and a human caring for his reader. But how to achieve that - is quite a different question too. Let's suppose this wonderfully written documentation is there.

How does one punch through the wall of indifference with just the title, a subtitle/tagline and one paragraph? What makes you care all of a sudden, even though a minute ago you couldn't even imagine you'd want to try this piece of software or at least read more about it?

Writing anything, it's useful to get into the mind of the people who will be using the software. Who are they, what type of work do they do, and why are they looking at the page are a few examples of questions to ponder. Step into their shoes and pretend to look at your page from their point of view. One of the things I've found useful when starting from scratch is to just put something out there and then keep the discussions/issues to communicate with people. If you have enough traffic, folks will ask questions. Each question has the potential for a conversation that lets you understand who these people are and what they're looking for. If you have enough interaction, you'll start seeing patterns (FAQs even) for areas that you can improve in the readme file. After you begin to address the things people care about, you'll see a decrease in the amount of questions in the covered areas, indicating that you're improving the documentation. Essentially, what I did was examine the audience, find a metric to measure progress, and iterate in the hopes of improving the docs.

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.

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.

Examples and screenshots are my favorite. I don't like it when there are too many distracting emojis.

Reply on news.ycombinator.com