Ask HN: What makes a README file awesome? | Hacker News Reader

Ask HN: What makes a README file awesome?

6 pointsfmerian9 comments

I recently read many thoughts on how to write a README file -- the most important part of a repo? -- and I'd love to have the opinion of the community here.

What makes a README file awesome from your point of view? What are the key elements you'd expect when reading one? Any good example?

And by 'awesome,' I mean a file that's resourceful and makes you want to contribute.

Thanks :)

View on HN

A good description of what the project does, installation instructions, and decent example usage where appropriate.

I like to show:

1. What it is.

2. How to install it.

3. What command-line flags there are, for CLI apps, or what the API is for embedding if a shared library.

4. Notes on how to run the tests.

5. A comment about reporting bugs.

Some projects have more sections, others less, but I think clear instructions for downloading/using, as well as a "What even is this?" is a good start.

> What makes a README file awesome from your point of view?

In general, a document that is clear, succinct and comprehensive gets my awesome upvote.

Actionnable: distinct sections with clear instructions (Requirements/Install/Tests) and the main entry point for every other piece of documentations.

Clear and concise, thanks!

Speaking of conciseness, is it important for you that a README file remains simple, short, and straight to the point?

A donation link would be nice. Maybe a Patreon, Ko-Fi, or Liberapay link so I can support the project.

Interesting! Do you think a project with a donation link is more serious than others? Does it encourage you to contribute beyond sponsorship?

If the project has a logo, it would be nice to add it to the README, if it uses Markdown

Set the hook. Love to have the TLDR, INSTALL and dependency info upfront. Do anything you want after that, but first I want to be on board with the basic premises.

Love it — Bookmarked.

Reply on news.ycombinator.com