HN Explorer

Ask HN: What makes a README file awesome?

6 points by fmerian ↗ HN
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 :)

9 comments

[ 5.2 ms ] story [ 31.9 ms ] thread
mdwalters
If the project has a logo, it would be nice to add it to the README, if it uses Markdown
leed25d
> 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.

aww_dang
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.
legrande
A donation link would be nice. Maybe a Patreon, Ko-Fi, or Liberapay link so I can support the project.
fmerian
Interesting! Do you think a project with a donation link is more serious than others? Does it encourage you to contribute beyond sponsorship?
skelzor
Actionnable: distinct sections with clear instructions (Requirements/Install/Tests) and the main entry point for every other piece of documentations.
fmerian
Clear and concise, thanks!

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

stevekemp
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.