Project documentation

README

The README page is the first thing your user will see!

The contents typically include one or more of the following:

  • Configuration instructions
  • Installation instructions
  • Operating instructions
  • A file manifest (list of files included)
  • Copyright and licensing information
  • Contact information for the distributor or programmer
  • Known bugs
  • Troubleshooting
  • Credits and acknowledgments

Example: why is this so important?

Example README

mcfly

README examples and templates

Some examples from projects with high quality documentation:

Bigger community software projects:

Research software:

Templates and ideas:

  • https://gist.github.com/PurpleBooth/109311bb0361f32d87a2
  • https://github.com/matiassingers/awesome-readme

README how?

  • When you create a repository on Github, there is an option to include a README file readme_github

  • READMEs are files that can be written as text, and commonly use Markdown for formatting.

  • Github will show the content of your README file at the root of the repository.

  • Your cookiecutter template included a README, so you are all set!

Your turn!

Edit your README file.

Make sure to include the following information:

  • What does your project do?

  • How do you start running your project?

  • How does the user download your project? (consider git clone!)

  • How does the user call the main script(s) that should be executed?

And perhaps any other elements you are inspired to add (check out the examples!)