Modern, interactive and impactful software documentation with Sphinx, MyST and the Diátaxis framework
Year: 2024
Type: conference-paper
Abstract: 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
Author: Vaillant, Ghislain
Language: English
Subfield: Information Systems and Management
Field: Decision Sciences
Domain: Social Sciences
Open Access status: green
OpenAlex ID: W4405299296