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 nine core elements of scientific software documentation. The resource also includes a playbook you can follow to prepare these nine 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.

Getting in Touch & Feedback

To report issues or propose improvements to One Good Tutorial, you are invited to start a conversation by filing an issue or a pull request on the One Good Tutorial source code repository on GitHub.

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, or for any other needs, contact him at pwilliams@cfa.harvard.edu.

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 1 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.11.1 and its DOI is 10.5281/zenodo.18676709. Cite it with a BibTeX entry like this:

@misc{onegoodtutorial0.11.1,
  author       = {Williams, Peter K. G.},
  title        = {One Good Tutorial (version 0.11.1)},
  year         = 2026,
  publisher    = {Zenodo},
  version      = {0.11.1},
  doi          = {10.5281/zenodo.18676709},
  url          = {https://doi.org/10.5281/zenodo.18676709}
}

(You may need to tweak the BibTeX content to get the correct citation text for your particular publication venue — this is fine.) See the “Export” section of the Zenodo page for additional formats.

Another, less-formal way to acknowledge One Good Tutorial is to add a compliance badge to your project README or another appropriate page.

Contributing to One Good Tutorial

Your contributions are most welcome! Start by exploring the One Good Tutorial source code repository on GitHub, where you can file an issue or a pull request. Or if you’re not sure exactly where to start, go ahead and get in touch with the author.

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

This work was supported by the Better Scientific Software Fellowship Program, a collaborative effort of the U.S. Department of Energy (DOE), Office of Advanced Scientific Computing Research via ANL under Contract DE-AC02-06CH11357 and the National Nuclear Security Administration Advanced Simulation and Computing Program via LLNL under Contract DE-AC52-07NA27344; and by the National Science Foundation (NSF) via SHI under Grant No. 2435328.