Comment on:
The following comment refers to this/these guideline(s)
Guideline 12
Documentation
Researchers document all information relevant to the production of a re- search result as clearly as is required by and is appropriate for the relevant subject area to allow the result to be reviewed and assessed. In general, this also includes documenting individual results that do not support the research hypothesis. The selection of results must be avoided. Where subject-specific recommendations exist for review and assessment, re- searchers create documentation in accordance with these guidelines. If the documentation does not satisfy these requirements, the constraints and the reasons for them are clearly explained. Documentation and re- search results must not be manipulated; they are protected as effectively as possible against manipulation.
Explanations:
An important basis for enabling replication is to make available the information necessary to understand the research (including the research data used or generated, the methodological, evaluation and analytical steps taken, and, if relevant, the development of the hypothesis), to ensure that citations are clear, and, as far as possible, to enable third parties to access this information. Where research software is being developed, the source code is documented.
Research software documentation
In Leitlinie 12 ist die umfassende Dokumentation von Informationen, Guideline 12 defines the comprehensive documentation of information relevant to the development of research findings as being a fundamental element of good research practice. Ensuring verifiability, reproducibility and replicability are key aims in connection with the use and development of research software, too. For this reason, every piece of research software used should be fully included in the documentation of project results (including version information, parameter settings, test/training datasets, etc.) and cited in accordance with subject-specific conventions. This documentation should be embedded in the research process and should be verifiable. It should be published together with or as part of the written documentation so that these results can likewise be assessed by the research community.
There may be cases in which research software cannot be fully documented for technical or disciplinary reasons, such as in cases where commercial and in-house components are combined, or where there is a potentially unlimited number of descriptive parameters. Here, it is crucial to document the properties and parameters of the software relevant to the research question to be documented – also including the source code itself wherever possible. In order to ensure effective documentation and citation of self-developed research software, metadata should be generated in a way that is as automated and standardised as possible. This includes linking it to electronic notebooks or lab books and selecting appropriate publication platforms for software. Once a certain technological level has been reached, or where there is significant relevance for users or a broader scope, it is advisable to register the research software.
The comment belongs to the following categories:
GL12 (General)
Keywords:
documentationresearch software