Documenting research software in engineering science.

Area of Science:

• Computer Science
• Engineering
• Scientific Research Methodology

Background:

• Research software reuse is hindered by inadequate documentation, a common criticism.
• Lack of documentation in non-IT fields is often blamed on training, time, or reward deficits.
• Existing recommendations for research software documentation may not align with researchers' actual practices.

Purpose of the Study:

• To investigate the hypothesis that scientists document research software but lack clarity on documentation requirements (what, why, for whom).
• To evaluate current research software documentation practices by comparing existing recommendations with real-world implementation.
• To identify gaps and provide a comprehensive understanding of research software documentation.

Main Methods:

• Examined existing recommendations for research software documentation.
• Evaluated the implementation of these recommendations using a case study from engineering sciences.
• Defined documentation categories to analyze the scope of research software documentation.

Main Results:

• The overall picture of research software documentation needs is often missing.
• Current recommendations overlook the primary documentation venue for researchers: their articles.
• Research software's historical context significantly impacts its documentation.

Conclusions:

• Scientists document research software, primarily within research articles, but require clearer guidelines.
• A comprehensive understanding of research software documentation, considering its history and the researcher's role, is needed.
• Best practices should integrate researchers' existing documentation habits and provide tailored guidance for effective software reuse.