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.<p>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?<p>And by 'awesome,' I mean a file that's resourceful and makes you want to contribute.<p>Thanks :)
A good description of what the project does, installation instructions, and decent example usage where appropriate.<p>I like to show:<p>1. What it is.<p>2. How to install it.<p>3. What command-line flags there are, for CLI apps, or what the API is for embedding if a shared library.<p>4. Notes on how to run the tests.<p>5. A comment about reporting bugs.<p>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?<p>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.
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.