re: How to write a good README? #discuss VIEW POST


I usually structure my READMEs like this:

  • Quick description of what the project is and what it does
  • A quickstart "tutorial" on how to start using it
    • Requirements
    • Installation
    • Configuration
    • How to use it
  • An update/upgrade guide (unless it's quite complex, then I'll just put a link to a wiki page or something)
  • Where to find the docs
  • How to contribute to the project
  • How to report bugs in the project
  • The license

The structure and content might vary depending on the project but that's the default "template" I use when I write a README.

I like it that way because users just need to take 5 minutes to read it and know what's what.


I like this as a standard, but I'd make a few quick changes if I were managing a very grand-scale project:

  • Move the license out to a separate file (Since it's not 100% necessary here, and Github and the like typically recognize a dedicated license file and have an easy link to it on the project page.

  • Have a very broad architecture/design section (probably after everything else), if the project isn't absurdly complex. This can give potential contributors a jumpstart if they want to help, but are having trouble putting together an overview of the file structure/software design. Obviously the trouble here is making sure it isn't too big for a readme.

  • I actually put the full license in a dedicated file and the "license" section of the README only contains a link to it. That's probably a bit redundant but it's an old habit from the time when GitHub did not include the license in the project page header.

  • That's usually something I put in the full documentation to keep the README more lightweight and free of unnecessary technical details.

code of conduct - report abuse