The README file is the first thing that users see when they visit your repository. It should provide a clear and concise overview of your project.
From the One Good Tutorial project, a good README should include the following (presented here as a handy checklist):
- 🗺️ Synopsis: 1-3 sentence summary of your project
- 📑 Tutorial: ✨ Show people what your software can do! ✨
- 👩🔧 Contact Information: How to ask a human about your software
- 🚀 Install Instructions: How to install your software
- 📜 Citation Instructions: How to cite your software
- 🙌 Contribution Statement: How users can contribute to your project
- 📚 Reference Material: Precise specifications of APIs, etc.
- ⚖️ Licensing Statement: The legal status of your code
- 🙏 Acknowledgments: Credit your funders
Examples of good README files include:
The contents of this repository were developed for use in an educational clinic at the 2026 CSDMS Annual Meeting. The materials were initially prepared following version 1 of the One Good Tutorial software documentation checklist. Funding for this work was provided by the U.S. National Science Foundation (NSF) under grant number 2148762, Collaborative Research: Facility: CSDMS: Engaging a thriving community of practice in Earth-surface dynamics.