Many of us aspire to provide high-quality documentation alongside our scientific software. However, we rarely have much time to write it, and it is easy to get stuck staring at the proverbial “blank page” when we finally sit down to begin.

In this talk, I present recommendations based on the concept of a “minimum viable documentation product”: what is the least amount of documentation you need to prepare while still serving your users well? These recommendations are collected in a new resource called One Good Tutorial, whose name captures the central idea. You need to provide one good tutorial that shows people how—and why—to use your code. You should provide more than that, but not much more. One Good Tutorial outlines a checklist of nine essential elements that your documentation should almost certainly include. The resource also offers a “playbook” with a suggested workflow for creating a new, checklist-compliant documentation set, along with supporting in-depth guides. I also discuss the design and implementation of the resource itself.

This work was supported by a 2025 Better Scientific Software Fellowship.

Presenter

• Peter K. G. Williams (Center for Astrophysics, Harvard & Smithsonian)

Presenter Bio

Peter K. G. Williams is an astrophysicist at the Center for Astrophysics | Harvard & Smithsonian. He received his PhD from UC Berkeley in 2012 and currently serves as the Technical Lead for the IAU Minor Planet Center, which is responsible for collecting, verifying, and distributing observations of asteroids, comets, and other small bodies in the Solar System from around the world. He has a long history of contributions to open-source software, including serving on the conda-forge core team from 2019 to 2024.