A beginner's guide to creating a README

If you are just starting out with open source one of the most important things to include is good documentation. This starts with a solid README file. At its core a README should include:

1. What does your project do? Share the vision of the need that your project is trying to meet.
2. How is it set up? If someone were to pick up your codebase today how would they get everything running in their local environment.
3. How is it used? Once it’s up and running provide some very descriptive examples of usage.
4. Is it in good shape? Do you have code climate, codeship, or other tools running to indicate the health of the project? Include information on dependencies as well.
5. How can others help? Collaboration yields amazing software. Make it easy for others to get involved by letting them know how to submit new features, report issues, or offer other assistance.
6. License information Don’t forget to let others know what license your project is released under. Not sure? Oreilly has an open book on understanding licensing.

You can extend this to include credits and acknowledgement, changelog details, and more but this will provide a solid foundation.

If you’re struggling with Markdown or basic formatting, here are some additional resources that might help:

• Help with markdown basics
• Github flavored markdown
• Basics of formatting the readme

Some template examples:

• Template for Github markdown and sublime
• Template for Github README
• Module template by Puppet Labs
• Readme template from the Drupal community
• Variety of specific readme templates