About One Good Tutorial

One Good Tutorial is an instructional resource for people who are documenting scientific software. The main idea is right there in the name: the most important thing is that your software’s documentation includes one good tutorial. You need a bit more than that, but not much more: the One Good Tutorial software documentation checklist defines eight core elements of scientific software documentation. The resource also includes a playbook you can follow to prepare these eight elements with a minimum of angst and a number of supporting in-depth guides.

One Good Tutorial was developed by Peter K. G. Williams with the support of a Better Scientific Software Fellowship.

Citing or Acknowledging One Good Tutorial

If you found this resource useful during the preparation of your software’s documentation, you are encouraged — but not obligated — to mention it in your acknowledgments section. A suggested statement is:

These materials were initially prepared following version beta of the One Good Tutorial software documentation checklist.

If you discuss One Good Tutorial in a scholarly context, you should cite it. You are reading version 0.9.7 and its DOI is 10.5281/zenodo.18363061. Cite it with the following BibTeX entry:

@misc{onegoodtutorial0.9.7,
  author       = {Williams, Peter K. G.},
  title        = {onegoodtutorial 0.9.7},
  year         = 2026,
  publisher    = {Zenodo},
  version      = {0.9.7},
  doi          = {10.5281/zenodo.18363061},
  url          = {https://doi.org/10.5281/zenodo.18363061}
}

See the “Export” section of the Zenodo page for additional formats.

Feedback

The BSSw team would like to collect feedback about the user impact of this resource. Please consider taking this three-minute survey if you have anything you’d like to convey; you can specify whether you’d like this feedback to be shared with the author, or not. To reach out to the author directly, see the next section.

Contributing to One Good Tutorial

Your contributions are most welcome! Reach out by filing an issue or even a pull request on the One Good Tutorial source code repository on GitHub, or contact to the author directly.

The One Good Tutorial website is built with a static site engine called Zola. To preview site changes in a local checkout of the source code, install Zola and use the command zola serve.

Changelog

You can find this project’s release notes by looking at the CHANGELOG.md file on the release branch of its repository or its GitHub release history.

Legalities

Acknowledgments

PKGW’s work on One Good Tutorial was supported by a Better Scientific Software Fellowship.