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:
- Clear, descriptive, unambiguous, memorable
- “What does it do”, including some context
- Could include links to e.g. personal portfolio site.
- Includes attribution for code you did not write.
- 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 zone-liner in the README. If you installed additional Python packages, list these in a
requirements.txtfile, and include a
sudo pip install -r requirements.txtone-liner in the README.
- Provide examples of how to run the code and expected results
- Describe any required input/output files.
- 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.
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.
- Description of what changed with each version. Since you’re using git, this can largely be replaced by quality commit messages.
- 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.
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 :)