Modern, interactive and impactful software documentation with Sphinx, MyST and the Diátaxis framework

Software documentation is often perceived as important by developers, yet insufficiently written or maintained over time [1]. Although it is accepted that good documentation is essential to both users and developers of research software, it is challenged by insufficient training, periodic staff turnover and minimal resources dedicated to knowledge sharing [2]. In this context, the Diátaxis framework [3] offers a valuable proposition for achieving an optimal and quality design for software documentation.This talk provides a practical introduction to the Diátaxis framework, using the Sphinx documentation tool coupled with the MyST ecosystem. The core principles behind the framework are first explained, followed by their application using Sphinx and MyST to produce quality materials, such as tutorials, cookbooks, user guides or developer references. The talk ends with some tips to automate and publish documentation alongside research code. [1]: https://doi.org/10.1145/2038476.2038509[2]: https://doi.org/10.1038/467775a[3]: https://diataxis.fr A recording of this session is available on YouTube: https://youtu.be/hdjb4rffEjM