15 ms·
Ask HN: 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 :)
- mdwalters 4y agoIf the project has a logo, it would be nice to add it to the README, if it uses Markdown
- leed25d 4y ago> 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 4y agoSet 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.
- fmerian 4y agoLove it — Bookmarked.
- legrande 4y agoA donation link would be nice. Maybe a Patreon, Ko-Fi, or Liberapay link so I can support the project.
- fmerian 4y agoInteresting! Do you think a project with a donation link is more serious than others? Does it encourage you to contribute beyond sponsorship?
- skelzor 4y agoActionnable: distinct sections with clear instructions (Requirements/Install/Tests) and the main entry point for every other piece of documentations.
- fmerian 4y agoClear and concise, thanks! Speaking of conciseness, is it important for you that a README file remains simple, short, and straight to the point?
- stevekemp 4y agoA 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.