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

TOP OF THREAD FULL DISCUSSION
re: 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...
 

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