Research Software Education and Documentation: The overlooked pillar of software sustainability and high quality science

How good can a research software be without proper documentation and training?

The crucial role of open and collaborative research software development in advancing high-quality research is increasingly recognized and valued within the scientific community and by funding sources. While attention often focuses on the software engineering aspects of research tools, the development of appropriate training materials remains frequently overlooked, with limited resources available to guide developers in creating effective tutorials and limited recognition of the work by academic evaluation. Though good examples of comprehensive documentation and training materials exist (e.g., DataLad, BIDS, various Python packages), the knowledge of how these materials were created - including the underlying thought processes and decisions - typically remains with their creators. Train-the-trainer programs such as those from ReproNim or Software Carpentry offer invaluable contributions in preparing peers for research software education; however, these programs have limited spots, and their resources for education of trainers are not enough known. Therefore, in my talk, I will emphasize the importance of creating educational and training materials for open-source research software and provide practical guidelines for developers.

The first part of my presentation will highlight the value of research software education materials. Acquiring proficiency in software not only increases scientific efficiency - researchers spend less time troubleshooting and more time conducting science with fewer errors - but well-designed tutorials also lower entry barriers to sophisticated analyses: without proper training materials, certain methods remain accessible only to those with advanced computational backgrounds. Well constructed tutorials break sophisticated techniques into manageable concepts with clear implementation steps. This democratizes science by enabling researchers from smaller institutions and under-resourced settings to implement cutting-edge techniques without extensive local expertise. Furthermore, a community of well-trained researchers contributes to software sustainability, beginning with user-driven documentation improvements and potentially advancing to code contributions. User feedback during training reveals necessary design improvements, creating tools that increasingly align with researchers’ actual workflows.

Key considerations in my talk will address existing training modalities (progressive complexity versus task-based approaches), how to determine which are most appropriate and effective for specific research software, the time investment required, and the sustainability challenges that arise. Through these discussions, I aim to emphasize that investing in high-quality training resources is central to research software development - particularly in complex domains like neuroimaging - and essential for maximizing the scientific impact of our tools. Actions to increase the value of software training should include recognition by the science community, e.g., with specific awards or quantification of the gains for software quality with good documentation. Finally, I will address the critical questions: who should be responsible for undertaking this task? And how do we make it sustainable?