Are you setting up documentation for new piece of scientific software? If so, make sure to include One Good Tutorial.
But you don’t need much more than that. According to the One Good Tutorial software documentation checklist (version 1), your documentation is good enough if it contains these nine major items:
| 🗺️ 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 |
The philosophy of One Good Tutorial is that while it would be wonderful if every project could have great docs, most new projects realistically have to aim for good enough. And what’s good enough? One good tutorial, because that’s what your new users need most, and the bare minimum of everything else. Write that minimum viable documentation product and go get your project out into the world! You can always add more later.
📒 The One Good Tutorial Playbook walks you through a tried-and-true workflow to prepare these nine items with a minimum of angst.
🗃️ Along with the playbook, this site provides in-depth guides and links to help you along your documentation journey.
One Good Tutorial was developed specifically to support the authors of scientific software, but we hope that it will be helpful to people who work on all kinds of technical projects. If you’ve found it useful, consider acknowledging One Good Tutorial and/or adding a badge to your README.
Learn more about One Good Tutorial on the About page.