This event is a part of the "Best Practices for HPC Software Developers" webinar series, produced by the IDEAS Productivity family of projects. The HPC Best Practices webinars address issues faced by developers of computational science and engineering (CSE) software on high-performance computers (HPC) and occur approximately monthly.
| Resource Information | Details |
|---|---|
| Webinar Title | One Good Tutorial: Defining a “Minimum Viable Documentation Product” for Scientific Software |
| Date and Time | 2026-03-18 1:00pm - 2:00pm EDT |
| Presenter | Peter K. G. Williams (Center for Astrophysics, Harvard & Smithsonian) |
| Registration, Information, and Archives | https://ideas-productivity.org/events/hpcbp-097-onegoodtutorial |
| Presentation Language | English |
Webinars are free and open to the public, but advance registration is required through the Event website. Archives (recording, slides, Q&A) will be posted at the same link soon after the event, and all registrants will be notified.
Abstract
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.
