README Rubric

Every software project should include a README, to give context for the project and help people get started using it. README files are helpful for your users and other developers - including yourself in the future! Elements of a good README include:

Title

• Clear, descriptive, unambiguous, memorable

Description

• “What does it do”, including some context

Authors

• Could include links to e.g. personal portfolio site.
• Includes attribution for code you did not write.

Getting Started

• Download instructions, optionally including versioning information and/or checksums.
• Installation instructions, including any required dependencies. You may assume that users start with the same environment you had on day 1 of the class. If your code depends on additional Ubuntu packages that are installed via apt-get install, include a sudo apt-get install x y z one-liner in the README. If you installed additional Python packages, list these in a requirements.txt file, and include a sudo pip install -r requirements.txt one-liner in the README.

Usage

• Provide examples of how to run the code and expected results
• Describe any required input/output files.

License

• Your final project represents a fair amount of your hard work, so you should think a bit about the terms on which you want to release it into the world. Check out Licensing a repository and http://choosealicense.com. Adding a license to repository makes it easier to add a license.

Developer-centric options

If you want others to contribute to your code, consider adding some of these additional sections:

How to Contribute

• Explicit instructions on the type of help you’re looking for and how you’d like to receive it.

Changelog

• Description of what changed with each version. Since you’re using git, this can largely be replaced by quality commit messages.

Implementation Details

• How the code works at a more detailed level.
• Description of files, data structures, etc. that it is important for new developers to be familiar with.

Other options

A few other sections that you could choose to include:

• List of Frequently-Asked Questions
• Links to peer/related projects
• Advertising “flavor text” promoting your work
• Multi-lingual information
• Tip jar :)