Clear documentation is critical to the success of your project. This checklist is meant to help you cover all your bases. Not every section/subsection will be relevant to your project; pick and choose what is. Inspired by READMEs of very successful projects like etcd.
Please copy-paste this into a new document and save as you build your READMEs. For alternative formats, you might create a Structured README, which offers a thorough breakdown of optional README ingredients for you to consider. You might also take a look at this similar checklist; or check out art-of-readme.
- Describe very briefly but clearly what the project does.
- State if it is out-of-the-box user-friendly, so it’s clear to the user.
- List its most useful/innovative/noteworthy features.
- State its goals/what problem(s) it solves.
- Note and briefly describe any key concepts (technical, philosophical, or both) important to the user’s understanding.
- Link to any supplementary blog posts or project main pages.
- Note its development status.
- Include badges.
- If possible, include screenshots and demo videos.
- Why does it exist?
- Frame your project for the potential user.
- Compare/contrast your project with other, similar projects so the user knows how it is different from those projects.
- Highlight the technical concepts that your project demonstrates or supports. Keep it very brief.
- Keep it useful.
Include any essential instructions for:
- Getting it
- Installing It
- Configuring It
- Running it
- Versioning: Services, APIs, Systems
- Common Error Messages/related details
- Tests
- Is it a Swift project? Please take a look at Mattt Thompson & Nate Cook's Swift documentation guide
- Contributor Guidelines
- Code Style/Requirements
- Format for commit messages
- Thank you (name contributors)
- Next steps
- Features planned
- Known bugs (shortlist)
- Email address
- Google Group/mailing list (if applicable)
- IRC or Slack (if applicable)