The README.md is the landing page for your project. It helps people understand, at a glance, whether your project is something that will be useful to them.
README files typically include information on:
- What the project does
- The features and benefits of the project
- How users can get started with the project
- Where users can get help with your project
- Who maintains and contributes to the project
Well written user documentation is the key to a great user experience. Experts say, "if a user can't figure out how to use your project in less than an hour, they will move on." It pays to attract a few technical writers to your project 😉
Where to create your documentation
Your user documentation should be easy for your users to find. Some prefer to keep it on an externally facing website while others will use a docs folder in their project or the repository wiki.
As an open source project becomes more popular and more sophisticated, some maintainers find it is easier to move their open source project into an a GitHub organization (Babel). This allows you to create separate repositories for your project's promotional website, documentation, source code, etc.
Documentation needs for open source projects will vary, but at a minimum you should include:
- Installation instructions
- Completing essential tasks
- Customizing and configuring