HACKER Q&A
📣 fmerian

What makes a README file awesome?


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 :)

  👤 stevekemp Accepted Answer ✓
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.

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

👤 skelzor
Actionnable: distinct sections with clear instructions (Requirements/Install/Tests) and the main entry point for every other piece of documentations.
👤 legrande
A donation link would be nice. Maybe a Patreon, Ko-Fi, or Liberapay link so I can support the project.
👤 mdwalters
If the project has a logo, it would be nice to add it to the README, if it uses Markdown
👤 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.