Documenting research software in engineering science

Abstract

The reuse of research software needs good documentation, however, the documentation in particular is often criticized. Especially in non-IT specific disciplines, the lack of documentation is attributed to the lack of training, the lack of time or missing rewards. This article addresses the hypothesis that scientists do document but do not know exactly what they need to document, why, and for whom. In order to evaluate the actual documentation practice of research software, we examined existing recommendations, and we evaluated their implementation in everyday practice using a concrete example from the engineering sciences and compared the findings with best practice examples. To get a broad overview of what documentation of research software entailed, we defined categories and used them to conduct the research. Our results show that the big picture of what documentation of research software means is missing. Recommendations do not consider the important role of researchers, who write research software, whose documentation takes mainly place in their research articles. Moreover, we show that research software always has a history that influences the documentation.

A Software Engineering Competency Inventory for Scientific Software Development Processes

“…Gereksinim yönetimi, güncel sınama yöntemleri ve tasarım modelleme gibi konuların ise önemli bulunsalar dahi belgeleme ve sürüm yönetimine göre az bilinen pratikler olduğu belirlenmiştir [13]. Ayrıca belgeleme gibi görece sık uygulanan pratiklerin bile gereken yetkinlik düzeyinde uygulanmadığı ve dolayısıyla gerekli işlevi yerine getiremediği de örnek bilimsel yazılım incelemeleriyle belirlenmiştir [12].…”

ENCORE. A practical implementation to improve reproducibility and transparency of computational research.

“…Training, scientific computing, and software engineering Over the past two decades, an increasing number of biomedical researchers have become involved in computational research. Many of these researchers have never been formally trained in scientific computing and software engineering (e.g., design, programming, documentation) (Hermann & Fehr, 2022;Martin, 2008), software version control (Blischak et al, 2016;Perez-Riverol et al, 2016), the use of high-performance computing infrastructures, the use of Unix/Linux which is still the major platform for scientific computing, algorithm design, the use of (Jupyter, R) notebooks (Rule et al, 2019), etc.…”

“…In addition, software documentation occasionally leaves much to desire. In a recent report, it was concluded that researchers are generally not aware for whom they write documentation and what documentation is required (Hermann & Fehr, 2022). Currently, ENCORE does not provide specific instructions for coding style (e.g., PEP 8 for Python and tidyverse for R; (Python Style Guide, 2024; Tidyverse Style Guide, 2024)) and documentation design because it is probably more effective to train scientist in the art of software engineering.…”

A sustainable infrastructure concept for improved accessibility, reusability, and archival of research software

“…Limited resources (time and skills) of research software developers and the lack of incentives in the academic research environment to assure the quality of research software are often suggested as the main problems leading to a lack of software sustainability and software quality assurance [5,15]. Research software is often not reusable because of missing documentation [16], broken links, or missing data [2]. However, in a survey on reproducibility, Elmenreich et al [17] found among more than 100 computer scientists, that researchers are both willing to spend time to reproduce their peer's research software artifacts (23 hours on average) and willing to spend time to make their own research reproducible by others (24 hours on average).…”