Drezil/doc_documentation
1
0
Fork 0
mirror of https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git synced 2025-06-07 09:34:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

more refinement. Not much left to polish

Browse Source
This commit is contained in:
Nicole Dresselhaus 2025-06-05 17:34:59 +02:00
parent dac7b3f039
commit 1dd2310caa
3 changed files with 245 additions and 878 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
background/BACKGROUND.html
View File

@ -2178,40 +2178,12 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<meta name="citation_reference" content="citation_title=Endings Principles for Digital Longevity;,citation_abstract=Enabling Sustainable Digital Humanities Projects;,citation_author=Endings Project Team;,citation_publication_date=2023-03-03;,citation_cover_date=2023-03-03;,citation_year=2023;,citation_fulltext_html_url=https://endings.uvic.ca/principles.html;,citation_language=en-US;">
<meta name="citation_reference" content="citation_title=Leitlinien zur Sicherung guter wissenschaftlicher Praxis;,citation_abstract=The DFG´s Code of Conduct “Safeguarding Good Research Practice” represents the consensus among the member organisations of the DFG on the fundamental principles and standards of good practice and are upheld by these organisations. These guidelines underline the importance of integrity in the everyday practice of research and provide researchers with a reliable reference with which to embed good research practice as an established and binding aspect of their work.;,citation_publication_date=2024-09;,citation_cover_date=2024-09;,citation_year=2024;,citation_fulltext_html_url=https://zenodo.org/records/14281892;,citation_doi=10.5281/zenodo.14281892;,citation_language=de-DE;,citation_publisher=Deutsche Forschungsgemeinschaft;">
<meta name="citation_reference" content="citation_title=Open Source Research Software;,citation_author=Wilhelm Hasselbring;,citation_author=Leslie Carr;,citation_author=Simon Hettrick;,citation_author=Heather Packer;,citation_author=Thanassis Tiropanis;,citation_publication_date=2020-08;,citation_cover_date=2020-08;,citation_year=2020;,citation_fulltext_html_url=https://ieeexplore.ieee.org/document/9153295/;,citation_issue=8;,citation_doi=10.1109/MC.2020.2998235;,citation_issn=0018-9162, 1558-0814;,citation_volume=53;,citation_journal_title=Computer;,citation_journal_abbrev=Computer;">
<meta name="citation_reference" content="citation_title=Trading Zones of Digital History;,citation_abstract=Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.;,citation_author=Max Kemman;,citation_publication_date=2021;,citation_cover_date=2021;,citation_year=2021;,citation_fulltext_html_url=https://www.degruyter.com/document/doi/10.1515/9783110682106/html;,citation_doi=10.1515/9783110682106;,citation_isbn=978-3-11-068210-6;,citation_language=en-US;,citation_series_title=Studies in Digital History and Hermeneutics;">
<meta name="citation_reference" content="citation_title=Four Simple Recommendations to Encourage Best Practices in Research Software;,citation_abstract=Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. This manuscript does not aim to propose new software development best practices, but rather to provide simple recommendations that encourage the adoption of existing best practices. Software development best practices promote better quality software, and better quality software improves the reproducibility and reusability of research. These recommendations are designed around Open Source values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent. This manuscript is aimed at developers, but also at organisations, projects, journals and funders that can increase the quality and sustainability of research software by encouraging the adoption of these recommendations.;,citation_author=Rafael C. Jiménez;,citation_author=Mateusz Kuzak;,citation_author=Monther Alhamdoosh;,citation_author=Michelle Barker;,citation_author=Bérénice Batut;,citation_author=Mikael Borg;,citation_author=Salvador Capella-Gutierrez;,citation_author=Neil Chue Hong;,citation_author=Martin Cook;,citation_author=Manuel Corpas;,citation_author=Madison Flannery;,citation_author=Leyla Garcia;,citation_author=Josep Ll. Gelpí;,citation_author=Simon Gladman;,citation_author=Carole Goble;,citation_author=Montserrat González Ferreiro;,citation_author=Alejandra Gonzalez-Beltran;,citation_author=Philippa C. Griffin;,citation_author=Björn Grüning;,citation_author=Jonas Hagberg;,citation_author=Petr Holub;,citation_author=Rob Hooft;,citation_author=Jon Ison;,citation_author=Daniel S. Katz;,citation_author=Brane Leskošek;,citation_author=Federico López Gómez;,citation_author=Luis J. Oliveira;,citation_author=David Mellor;,citation_author=Rowland Mosbergen;,citation_author=Nicola Mulder;,citation_author=Yasset Perez-Riverol;,citation_author=Robert Pergl;,citation_author=Horst Pichler;,citation_author=Bernard Pope;,citation_author=Ferran Sanz;,citation_author=Maria V. Schneider;,citation_author=Victoria Stodden;,citation_author=Radosław Suchecki;,citation_author=Radka Svobodová Vařeková;,citation_author=Harry-Anton Talvik;,citation_author=Ilian Todorov;,citation_author=Andrew Treloar;,citation_author=Sonika Tyagi;,citation_author=Maarten Van Gompel;,citation_author=Daniel Vaughan;,citation_author=Allegra Via;,citation_author=Xiaochuan Wang;,citation_author=Nathan S. Watson-Haigh;,citation_author=Steve Crouch;,citation_publication_date=2017-06-13;,citation_cover_date=2017-06-13;,citation_year=2017;,citation_fulltext_html_url=https://f1000research.com/articles/6-876/v1;,citation_doi=10.12688/f1000research.11407.1;,citation_issn=2046-1402;,citation_volume=6;,citation_language=en-US;,citation_journal_title=F1000Research;,citation_journal_abbrev=F1000Res;">
<meta name="citation_reference" content="citation_title=Jupyter Notebooks – a Publishing Format for Reproducible Computational Workflows;,citation_abstract=It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.;,citation_author=Thomas Kluyver;,citation_author=Benjamin Ragan-Kelley;,citation_author=Fernando Pérez;,citation_author=Brian Granger;,citation_author=Matthias Bussonnier;,citation_author=Jonathan Frederic;,citation_author=Kyle Kelley;,citation_author=Jessica Hamrick;,citation_author=Jason Grout;,citation_author=Sylvain Corlay;,citation_author=Paul Ivanov;,citation_author=Damián Avila;,citation_author=Safia Abdalla;,citation_author=Carol Willing;,citation_author=Jupyter team;,citation_editor=Fernando Loizides;,citation_editor=Birgit Scmidt;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_fulltext_html_url=https://eprints.soton.ac.uk/403913/;,citation_doi=10.3233/978-1-61499-649-1-87;,citation_language=en-US;,citation_conference=IOS Press;">
<meta name="citation_reference" content="citation_title=Towards FAIR Principles for Research Software;,citation_abstract=The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.;,citation_author=Anna-Lena Lamprecht;,citation_author=Leyla Garcia;,citation_author=Mateusz Kuzak;,citation_author=Carlos Martinez;,citation_author=Ricardo Arcila;,citation_author=Eva Martin Del Pico;,citation_author=Victoria Dominguez Del Angel;,citation_author=Stephanie Sandt;,citation_author=Jon Ison;,citation_author=Paula Andrea Martinez;,citation_author=Peter McQuilton;,citation_author=Alfonso Valencia;,citation_author=Jennifer Harrow;,citation_author=Fotis Psomopoulos;,citation_author=Josep Ll. Gelpi;,citation_author=Neil Chue Hong;,citation_author=Carole Goble;,citation_author=Salvador Capella-Gutierrez;,citation_publication_date=2020-06-12;,citation_cover_date=2020-06-12;,citation_year=2020;,citation_fulltext_html_url=https://doi.org/10.3233/DS-190026;,citation_issue=1;,citation_doi=10.3233/DS-190026;,citation_issn=2451-8484;,citation_volume=3;,citation_language=en-US;,citation_journal_title=Data Science;,citation_publisher=SAGE Publications;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for Documenting Scientific Software;,citation_author=Benjamin D. Lee;,citation_publication_date=2018-12-20;,citation_cover_date=2018-12-20;,citation_year=2018;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561;,citation_issue=12;,citation_doi=10.1371/journal.pcbi.1006561;,citation_issn=1553-7358;,citation_volume=14;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Software Citation Principles;,citation_abstract=Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.;,citation_author=Arfon M. Smith;,citation_author=Daniel S. Katz;,citation_author=Kyle E. Niemeyer;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_fulltext_html_url=https://peerj.com/articles/cs-86;,citation_doi=10.7717/peerj-cs.86;,citation_issn=2376-5992;,citation_volume=2;,citation_language=en-US;,citation_journal_title=PeerJ Computer Science;,citation_journal_abbrev=PeerJ Comput. Sci.;,citation_publisher=PeerJ Inc.;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for the Open Development of Scientific Software;,citation_author=Andreas Prlić;,citation_author=James B. Procter;,citation_publication_date=2012-12-06;,citation_cover_date=2012-12-06;,citation_year=2012;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802;,citation_issue=12;,citation_doi=10.1371/journal.pcbi.1002802;,citation_issn=1553-7358;,citation_volume=8;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Good Enough Practices in Scientific Computing;,citation_abstract=Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don’t know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.;,citation_author=Greg Wilson;,citation_author=Jennifer Bryan;,citation_author=Karen Cranston;,citation_author=Justin Kitzes;,citation_author=Lex Nederbragt;,citation_author=Tracy K. Teal;,citation_publication_date=2017-06-22;,citation_cover_date=2017-06-22;,citation_year=2017;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510;,citation_issue=6;,citation_doi=10.1371/journal.pcbi.1005510;,citation_issn=1553-7358;,citation_volume=13;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Collaborative Historical Research in the Age of Big Data: Lessons from an Interdisciplinary Project;,citation_abstract=This book is output of the Living with Machines project;,citation_author=Ruth Ahnert;,citation_author=Emma Griffin;,citation_author=Mia Ridge;,citation_author=Giorgia Tolfo;,citation_publication_date=2023;,citation_cover_date=2023;,citation_year=2023;,citation_fulltext_html_url=https://www.cambridge.org/core/elements/collaborative-historical-research-in-the-age-of-big-data/839C422CCAA6C1699DE8D353B3A1960D;,citation_doi=10.1017/9781009175548;,citation_language=en-US;,citation_series_title=Cambridge Elements: Historical Theory and Practice;">
<meta name="citation_reference" content="citation_title=DFG-Praxisregeln &amp;amp;amp;quot;Digitalisierung&amp;quot;. Aktualisierte Fassung 2022.;,citation_abstract=Die DFG-Praxisregeln „Digitalisierung“ stellen eine zentrale Grundlage für DFG-geförderte Projekte im Programm „Digitalisierung und Erschließung“ dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschließung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zugänglichkeit und Anschlussfähigkeit geförderter Projekte und der in diesem Zusammenhang entstehenden Infrastruktur. Das vorliegende Dokument stellt eine aktualisierte Fassung der zuletzt 2016 durch die DFG publizierten Praxisregeln dar. Es wurde in Absprache mit der DFG-Geschäftsstelle durch eine vom NFDI-Konsortium NFDI4Culture initiierte Autor*innengruppe erarbeitet, deren Mitglieder mehrheitlich seit langem an der Ausgestaltung der Praxisregeln beteiligt waren sowie aktiv in die NFDI-Konsortien NFDI4Culture, NFDI4Memory, NFDI4Objects und Text+ eingebunden sind. Die jetzt überarbeitet vorliegenden Praxisregeln „Digitalisierung“ dienen als Ausgangspunkt für eine material- und communitybezogene Ausdifferenzierung der Praxisregeln durch die Communitys. Alle mit der Digitalisierung forschungsrelevanter Objekte befassten Communitys und Einrichtungen sind dazu aufgerufen, mit ihrer Expertise am weiteren Prozess mitzuwirken.;,citation_author=Reinhard Altenhöner;,citation_author=Andreas Berger;,citation_author=Christian Bracht;,citation_author=Paul Klimpel;,citation_author=Sebastian Meyer;,citation_author=Andreas Neuburger;,citation_author=Thomas Stäcker;,citation_author=Regine Stein;,citation_publication_date=2023-02-16;,citation_cover_date=2023-02-16;,citation_year=2023;,citation_fulltext_html_url=https://zenodo.org/record/7435724;,citation_language=deu;">
<meta name="citation_reference" content="citation_title=Introducing the FAIR Principles for Research Software;,citation_abstract=Research software is a fundamental and vital part of research, yet significant challenges to discoverability, productivity, quality, reproducibility, and sustainability exist. Improving the practice of scholarship is a common goal of the open science, open source, and FAIR (Findable, Accessible, Interoperable and Reusable) communities and research software is now being understood as a type of digital object to which FAIR should be applied. This emergence reflects a maturation of the research community to better understand the crucial role of FAIR research software in maximising research value. The FAIR for Research Software (FAIR4RS) Working Group has adapted the FAIR Guiding Principles to create the FAIR Principles for Research Software (FAIR4RS Principles). The contents and context of the FAIR4RS Principles are summarised here to provide the basis for discussion of their adoption. Examples of implementation by organisations are provided to share information on how to maximise the value of research outputs, and to encourage others to amplify the importance and impact of this work.;,citation_author=Michelle Barker;,citation_author=Neil P. Chue Hong;,citation_author=Daniel S. Katz;,citation_author=Anna-Lena Lamprecht;,citation_author=Carlos Martinez-Ortiz;,citation_author=Fotis Psomopoulos;,citation_author=Jennifer Harrow;,citation_author=Leyla Jael Castro;,citation_author=Morane Gruenpeter;,citation_author=Paula Andrea Martinez;,citation_author=Tom Honeyman;,citation_publication_date=2022-10-14;,citation_cover_date=2022-10-14;,citation_year=2022;,citation_fulltext_html_url=https://www.nature.com/articles/s41597-022-01710-x;,citation_issue=1;,citation_doi=10.1038/s41597-022-01710-x;,citation_issn=2052-4463;,citation_volume=9;,citation_language=en-US;,citation_journal_title=Scientific Data;,citation_journal_abbrev=Sci Data;,citation_publisher=Nature Publishing Group;">
<meta name="citation_reference" content="citation_title=Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit;,citation_abstract=Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.;,citation_editor=Fabian Cremer;,citation_editor=Swantje Dogunke;,citation_editor=Anna Maria Neubert;,citation_editor=Thorsten Wübbena;,citation_publication_date=2024-04;,citation_cover_date=2024-04;,citation_year=2024;,citation_doi=10.14361/9783839469675;,citation_language=de-DE;">
<meta name="citation_reference" content="citation_title=The Journal of Open Source Software (JOSS): Bringing Open-Source Software Practices to the Scholarly Publishing Community for Authors, Reviewers, Editors, and Publishers;,citation_abstract=Introduction: Open-source software (OSS) is a critical component of open science, but contributions to the OSS ecosystem are systematically undervalued in the current academic system. The Journal of Open Source Software (JOSS) contributes to addressing this by providing a venue (that is itself free, diamond open access, and all open-source, built in a layered structure using widely available elements/services of the scholarly publishing ecosystem) for publishing OSS, run in the style of OSS itself. A particularly distinctive element of JOSS is that it uses open peer review in a collaborative, iterative format, unlike most publishers. Additionally, all the components of the process—from the reviews to the papers to the software that is the subject of the papers to the software that the journal runs—are open. Background: We describe JOSS’s history and its peer review process using an editorial bot, and we present statistics gathered from JOSS’s public review history on GitHub showing an increasing number of peer reviewed papers each year. We discuss the new JOSSCast and use it as a data source to understand reasons why interviewed authors decided to publish in JOSS. Discussion and Outlook: JOSS’s process differs significantly from traditional journals, which has impeded JOSS’s inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italy’s, which emphasize the importance of Web of Science and/or Scopus indexing for grant applications and promotions. JOSS is a fully diamond open-access journal with a cost of around US$5 per paper for the 401 papers published in 2023. The scalability of running JOSS with volunteers and financing JOSS with grants and donations is discussed.;,citation_author=Patrick Diehl;,citation_author=Charlotte Soneson;,citation_author=Rachel C. Kurchin;,citation_author=Ross Mounce;,citation_author=Daniel S. Katz;,citation_publication_date=2025-02-04;,citation_cover_date=2025-02-04;,citation_year=2025;,citation_fulltext_html_url=https://www.iastatedigitalpress.com/jlsc/article/id/18285/;,citation_issue=2, 2;,citation_doi=10.31274/jlsc.18285;,citation_issn=2162-3309;,citation_volume=12;,citation_language=en-US;,citation_journal_title=Journal of Librarianship and Scholarly Communication;,citation_publisher=Iowa State University Digital Press;">
<meta name="citation_reference" content="citation_title=Endings Principles for Digital Longevity;,citation_abstract=Enabling Sustainable Digital Humanities Projects;,citation_author=Endings Project Team;,citation_publication_date=2023-03-03;,citation_cover_date=2023-03-03;,citation_year=2023;,citation_fulltext_html_url=https://endings.uvic.ca/principles.html;,citation_language=en-US;">
<meta name="citation_reference" content="citation_title=Leitlinien zur Sicherung guter wissenschaftlicher Praxis;,citation_abstract=The DFG´s Code of Conduct “Safeguarding Good Research Practice” represents the consensus among the member organisations of the DFG on the fundamental principles and standards of good practice and are upheld by these organisations. These guidelines underline the importance of integrity in the everyday practice of research and provide researchers with a reliable reference with which to embed good research practice as an established and binding aspect of their work.;,citation_publication_date=2024-09;,citation_cover_date=2024-09;,citation_year=2024;,citation_fulltext_html_url=https://zenodo.org/records/14281892;,citation_doi=10.5281/zenodo.14281892;,citation_language=de-DE;,citation_publisher=Deutsche Forschungsgemeinschaft;">
<meta name="citation_reference" content="citation_title=Trading Zones of Digital History;,citation_abstract=Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.;,citation_author=Max Kemman;,citation_publication_date=2021;,citation_cover_date=2021;,citation_year=2021;,citation_fulltext_html_url=https://www.degruyter.com/document/doi/10.1515/9783110682106/html;,citation_doi=10.1515/9783110682106;,citation_isbn=978-3-11-068210-6;,citation_language=en-US;,citation_series_title=Studies in Digital History and Hermeneutics;">
<meta name="citation_reference" content="citation_title=Jupyter Notebooks – a Publishing Format for Reproducible Computational Workflows;,citation_abstract=It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.;,citation_author=Thomas Kluyver;,citation_author=Benjamin Ragan-Kelley;,citation_author=Fernando Pérez;,citation_author=Brian Granger;,citation_author=Matthias Bussonnier;,citation_author=Jonathan Frederic;,citation_author=Kyle Kelley;,citation_author=Jessica Hamrick;,citation_author=Jason Grout;,citation_author=Sylvain Corlay;,citation_author=Paul Ivanov;,citation_author=Damián Avila;,citation_author=Safia Abdalla;,citation_author=Carol Willing;,citation_author=Jupyter team;,citation_editor=Fernando Loizides;,citation_editor=Birgit Scmidt;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_fulltext_html_url=https://eprints.soton.ac.uk/403913/;,citation_doi=10.3233/978-1-61499-649-1-87;,citation_language=en-US;,citation_conference=IOS Press;">
<meta name="citation_reference" content="citation_title=Towards FAIR Principles for Research Software;,citation_abstract=The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.;,citation_author=Anna-Lena Lamprecht;,citation_author=Leyla Garcia;,citation_author=Mateusz Kuzak;,citation_author=Carlos Martinez;,citation_author=Ricardo Arcila;,citation_author=Eva Martin Del Pico;,citation_author=Victoria Dominguez Del Angel;,citation_author=Stephanie Sandt;,citation_author=Jon Ison;,citation_author=Paula Andrea Martinez;,citation_author=Peter McQuilton;,citation_author=Alfonso Valencia;,citation_author=Jennifer Harrow;,citation_author=Fotis Psomopoulos;,citation_author=Josep Ll. Gelpi;,citation_author=Neil Chue Hong;,citation_author=Carole Goble;,citation_author=Salvador Capella-Gutierrez;,citation_publication_date=2020-06-12;,citation_cover_date=2020-06-12;,citation_year=2020;,citation_fulltext_html_url=https://doi.org/10.3233/DS-190026;,citation_issue=1;,citation_doi=10.3233/DS-190026;,citation_issn=2451-8484;,citation_volume=3;,citation_language=en-US;,citation_journal_title=Data Science;,citation_publisher=SAGE Publications;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for Documenting Scientific Software;,citation_author=Benjamin D. Lee;,citation_publication_date=2018-12-20;,citation_cover_date=2018-12-20;,citation_year=2018;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561;,citation_issue=12;,citation_doi=10.1371/journal.pcbi.1006561;,citation_issn=1553-7358;,citation_volume=14;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Software Citation Principles;,citation_abstract=Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.;,citation_author=Arfon M. Smith;,citation_author=Daniel S. Katz;,citation_author=Kyle E. Niemeyer;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_fulltext_html_url=https://peerj.com/articles/cs-86;,citation_doi=10.7717/peerj-cs.86;,citation_issn=2376-5992;,citation_volume=2;,citation_language=en-US;,citation_journal_title=PeerJ Computer Science;,citation_journal_abbrev=PeerJ Comput. Sci.;,citation_publisher=PeerJ Inc.;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for the Open Development of Scientific Software;,citation_author=Andreas Prlić;,citation_author=James B. Procter;,citation_publication_date=2012-12-06;,citation_cover_date=2012-12-06;,citation_year=2012;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802;,citation_issue=12;,citation_doi=10.1371/journal.pcbi.1002802;,citation_issn=1553-7358;,citation_volume=8;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Good Enough Practices in Scientific Computing;,citation_abstract=Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don’t know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.;,citation_author=Greg Wilson;,citation_author=Jennifer Bryan;,citation_author=Karen Cranston;,citation_author=Justin Kitzes;,citation_author=Lex Nederbragt;,citation_author=Tracy K. Teal;,citation_publication_date=2017-06-22;,citation_cover_date=2017-06-22;,citation_year=2017;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510;,citation_issue=6;,citation_doi=10.1371/journal.pcbi.1005510;,citation_issn=1553-7358;,citation_volume=13;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Collaborative Historical Research in the Age of Big Data: Lessons from an Interdisciplinary Project;,citation_abstract=This book is output of the Living with Machines project;,citation_author=Ruth Ahnert;,citation_author=Emma Griffin;,citation_author=Mia Ridge;,citation_author=Giorgia Tolfo;,citation_publication_date=2023;,citation_cover_date=2023;,citation_year=2023;,citation_fulltext_html_url=https://www.cambridge.org/core/elements/collaborative-historical-research-in-the-age-of-big-data/839C422CCAA6C1699DE8D353B3A1960D;,citation_doi=10.1017/9781009175548;,citation_language=en-US;,citation_series_title=Cambridge Elements: Historical Theory and Practice;">
<meta name="citation_reference" content="citation_title=DFG-Praxisregeln &amp;amp;amp;quot;Digitalisierung&amp;quot;. Aktualisierte Fassung 2022.;,citation_abstract=Die DFG-Praxisregeln „Digitalisierung“ stellen eine zentrale Grundlage für DFG-geförderte Projekte im Programm „Digitalisierung und Erschließung“ dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschließung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zugänglichkeit und Anschlussfähigkeit geförderter Projekte und der in diesem Zusammenhang entstehenden Infrastruktur. Das vorliegende Dokument stellt eine aktualisierte Fassung der zuletzt 2016 durch die DFG publizierten Praxisregeln dar. Es wurde in Absprache mit der DFG-Geschäftsstelle durch eine vom NFDI-Konsortium NFDI4Culture initiierte Autor*innengruppe erarbeitet, deren Mitglieder mehrheitlich seit langem an der Ausgestaltung der Praxisregeln beteiligt waren sowie aktiv in die NFDI-Konsortien NFDI4Culture, NFDI4Memory, NFDI4Objects und Text+ eingebunden sind. Die jetzt überarbeitet vorliegenden Praxisregeln „Digitalisierung“ dienen als Ausgangspunkt für eine material- und communitybezogene Ausdifferenzierung der Praxisregeln durch die Communitys. Alle mit der Digitalisierung forschungsrelevanter Objekte befassten Communitys und Einrichtungen sind dazu aufgerufen, mit ihrer Expertise am weiteren Prozess mitzuwirken.;,citation_author=Reinhard Altenhöner;,citation_author=Andreas Berger;,citation_author=Christian Bracht;,citation_author=Paul Klimpel;,citation_author=Sebastian Meyer;,citation_author=Andreas Neuburger;,citation_author=Thomas Stäcker;,citation_author=Regine Stein;,citation_publication_date=2023-02-16;,citation_cover_date=2023-02-16;,citation_year=2023;,citation_fulltext_html_url=https://zenodo.org/record/7435724;,citation_language=deu;">
<meta name="citation_reference" content="citation_title=Introducing the FAIR Principles for Research Software;,citation_abstract=Research software is a fundamental and vital part of research, yet significant challenges to discoverability, productivity, quality, reproducibility, and sustainability exist. Improving the practice of scholarship is a common goal of the open science, open source, and FAIR (Findable, Accessible, Interoperable and Reusable) communities and research software is now being understood as a type of digital object to which FAIR should be applied. This emergence reflects a maturation of the research community to better understand the crucial role of FAIR research software in maximising research value. The FAIR for Research Software (FAIR4RS) Working Group has adapted the FAIR Guiding Principles to create the FAIR Principles for Research Software (FAIR4RS Principles). The contents and context of the FAIR4RS Principles are summarised here to provide the basis for discussion of their adoption. Examples of implementation by organisations are provided to share information on how to maximise the value of research outputs, and to encourage others to amplify the importance and impact of this work.;,citation_author=Michelle Barker;,citation_author=Neil P. Chue Hong;,citation_author=Daniel S. Katz;,citation_author=Anna-Lena Lamprecht;,citation_author=Carlos Martinez-Ortiz;,citation_author=Fotis Psomopoulos;,citation_author=Jennifer Harrow;,citation_author=Leyla Jael Castro;,citation_author=Morane Gruenpeter;,citation_author=Paula Andrea Martinez;,citation_author=Tom Honeyman;,citation_publication_date=2022-10-14;,citation_cover_date=2022-10-14;,citation_year=2022;,citation_fulltext_html_url=https://www.nature.com/articles/s41597-022-01710-x;,citation_issue=1;,citation_doi=10.1038/s41597-022-01710-x;,citation_issn=2052-4463;,citation_volume=9;,citation_language=en-US;,citation_journal_title=Scientific Data;,citation_journal_abbrev=Sci Data;,citation_publisher=Nature Publishing Group;">
<meta name="citation_reference" content="citation_title=Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit;,citation_abstract=Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.;,citation_editor=Fabian Cremer;,citation_editor=Swantje Dogunke;,citation_editor=Anna Maria Neubert;,citation_editor=Thorsten Wübbena;,citation_publication_date=2024-04;,citation_cover_date=2024-04;,citation_year=2024;,citation_doi=10.14361/9783839469675;,citation_language=de-DE;">
<meta name="citation_reference" content="citation_title=The Journal of Open Source Software (JOSS): Bringing Open-Source Software Practices to the Scholarly Publishing Community for Authors, Reviewers, Editors, and Publishers;,citation_abstract=Introduction: Open-source software (OSS) is a critical component of open science, but contributions to the OSS ecosystem are systematically undervalued in the current academic system. The Journal of Open Source Software (JOSS) contributes to addressing this by providing a venue (that is itself free, diamond open access, and all open-source, built in a layered structure using widely available elements/services of the scholarly publishing ecosystem) for publishing OSS, run in the style of OSS itself. A particularly distinctive element of JOSS is that it uses open peer review in a collaborative, iterative format, unlike most publishers. Additionally, all the components of the process—from the reviews to the papers to the software that is the subject of the papers to the software that the journal runs—are open. Background: We describe JOSS’s history and its peer review process using an editorial bot, and we present statistics gathered from JOSS’s public review history on GitHub showing an increasing number of peer reviewed papers each year. We discuss the new JOSSCast and use it as a data source to understand reasons why interviewed authors decided to publish in JOSS. Discussion and Outlook: JOSS’s process differs significantly from traditional journals, which has impeded JOSS’s inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italy’s, which emphasize the importance of Web of Science and/or Scopus indexing for grant applications and promotions. JOSS is a fully diamond open-access journal with a cost of around US$5 per paper for the 401 papers published in 2023. The scalability of running JOSS with volunteers and financing JOSS with grants and donations is discussed.;,citation_author=Patrick Diehl;,citation_author=Charlotte Soneson;,citation_author=Rachel C. Kurchin;,citation_author=Ross Mounce;,citation_author=Daniel S. Katz;,citation_publication_date=2025-02-04;,citation_cover_date=2025-02-04;,citation_year=2025;,citation_fulltext_html_url=https://www.iastatedigitalpress.com/jlsc/article/id/18285/;,citation_issue=2, 2;,citation_doi=10.31274/jlsc.18285;,citation_issn=2162-3309;,citation_volume=12;,citation_language=en-US;,citation_journal_title=Journal of Librarianship and Scholarly Communication;,citation_publisher=Iowa State University Digital Press;">
<meta name="citation_reference" content="citation_title=Endings Principles for Digital Longevity;,citation_abstract=Enabling Sustainable Digital Humanities Projects;,citation_author=Endings Project Team;,citation_publication_date=2023-03-03;,citation_cover_date=2023-03-03;,citation_year=2023;,citation_fulltext_html_url=https://endings.uvic.ca/principles.html;,citation_language=en-US;">
<meta name="citation_reference" content="citation_title=Leitlinien zur Sicherung guter wissenschaftlicher Praxis;,citation_abstract=The DFG´s Code of Conduct “Safeguarding Good Research Practice” represents the consensus among the member organisations of the DFG on the fundamental principles and standards of good practice and are upheld by these organisations. These guidelines underline the importance of integrity in the everyday practice of research and provide researchers with a reliable reference with which to embed good research practice as an established and binding aspect of their work.;,citation_publication_date=2024-09;,citation_cover_date=2024-09;,citation_year=2024;,citation_fulltext_html_url=https://zenodo.org/records/14281892;,citation_doi=10.5281/zenodo.14281892;,citation_language=de-DE;,citation_publisher=Deutsche Forschungsgemeinschaft;">
<meta name="citation_reference" content="citation_title=Trading Zones of Digital History;,citation_abstract=Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.;,citation_author=Max Kemman;,citation_publication_date=2021;,citation_cover_date=2021;,citation_year=2021;,citation_fulltext_html_url=https://www.degruyter.com/document/doi/10.1515/9783110682106/html;,citation_doi=10.1515/9783110682106;,citation_isbn=978-3-11-068210-6;,citation_language=en-US;,citation_series_title=Studies in Digital History and Hermeneutics;">
<meta name="citation_reference" content="citation_title=Jupyter Notebooks – a Publishing Format for Reproducible Computational Workflows;,citation_abstract=It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.;,citation_author=Thomas Kluyver;,citation_author=Benjamin Ragan-Kelley;,citation_author=Fernando Pérez;,citation_author=Brian Granger;,citation_author=Matthias Bussonnier;,citation_author=Jonathan Frederic;,citation_author=Kyle Kelley;,citation_author=Jessica Hamrick;,citation_author=Jason Grout;,citation_author=Sylvain Corlay;,citation_author=Paul Ivanov;,citation_author=Damián Avila;,citation_author=Safia Abdalla;,citation_author=Carol Willing;,citation_author=Jupyter team;,citation_editor=Fernando Loizides;,citation_editor=Birgit Scmidt;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_fulltext_html_url=https://eprints.soton.ac.uk/403913/;,citation_doi=10.3233/978-1-61499-649-1-87;,citation_language=en-US;,citation_conference=IOS Press;">
<meta name="citation_reference" content="citation_title=Towards FAIR Principles for Research Software;,citation_abstract=The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.;,citation_author=Anna-Lena Lamprecht;,citation_author=Leyla Garcia;,citation_author=Mateusz Kuzak;,citation_author=Carlos Martinez;,citation_author=Ricardo Arcila;,citation_author=Eva Martin Del Pico;,citation_author=Victoria Dominguez Del Angel;,citation_author=Stephanie Sandt;,citation_author=Jon Ison;,citation_author=Paula Andrea Martinez;,citation_author=Peter McQuilton;,citation_author=Alfonso Valencia;,citation_author=Jennifer Harrow;,citation_author=Fotis Psomopoulos;,citation_author=Josep Ll. Gelpi;,citation_author=Neil Chue Hong;,citation_author=Carole Goble;,citation_author=Salvador Capella-Gutierrez;,citation_publication_date=2020-06-12;,citation_cover_date=2020-06-12;,citation_year=2020;,citation_fulltext_html_url=https://doi.org/10.3233/DS-190026;,citation_issue=1;,citation_doi=10.3233/DS-190026;,citation_issn=2451-8484;,citation_volume=3;,citation_language=en-US;,citation_journal_title=Data Science;,citation_publisher=SAGE Publications;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for Documenting Scientific Software;,citation_author=Benjamin D. Lee;,citation_publication_date=2018-12-20;,citation_cover_date=2018-12-20;,citation_year=2018;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561;,citation_issue=12;,citation_doi=10.1371/journal.pcbi.1006561;,citation_issn=1553-7358;,citation_volume=14;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Software Citation Principles;,citation_abstract=Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.;,citation_author=Arfon M. Smith;,citation_author=Daniel S. Katz;,citation_author=Kyle E. Niemeyer;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_fulltext_html_url=https://peerj.com/articles/cs-86;,citation_doi=10.7717/peerj-cs.86;,citation_issn=2376-5992;,citation_volume=2;,citation_language=en-US;,citation_journal_title=PeerJ Computer Science;,citation_journal_abbrev=PeerJ Comput. Sci.;,citation_publisher=PeerJ Inc.;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for the Open Development of Scientific Software;,citation_author=Andreas Prlić;,citation_author=James B. Procter;,citation_publication_date=2012-12-06;,citation_cover_date=2012-12-06;,citation_year=2012;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802;,citation_issue=12;,citation_doi=10.1371/journal.pcbi.1002802;,citation_issn=1553-7358;,citation_volume=8;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Good Enough Practices in Scientific Computing;,citation_abstract=Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don’t know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.;,citation_author=Greg Wilson;,citation_author=Jennifer Bryan;,citation_author=Karen Cranston;,citation_author=Justin Kitzes;,citation_author=Lex Nederbragt;,citation_author=Tracy K. Teal;,citation_publication_date=2017-06-22;,citation_cover_date=2017-06-22;,citation_year=2017;,citation_fulltext_html_url=https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510;,citation_issue=6;,citation_doi=10.1371/journal.pcbi.1005510;,citation_issn=1553-7358;,citation_volume=13;,citation_language=en-US;,citation_journal_title=PLOS Computational Biology;,citation_journal_abbrev=PLOS Computational Biology;,citation_publisher=Public Library of Science;">
</head>
@ -2242,17 +2214,13 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<li><a href="#strukturierte-unterteilung-in-weitere-dateienabschnitte" id="toc-strukturierte-unterteilung-in-weitere-dateienabschnitte" class="nav-link" data-scroll-target="#strukturierte-unterteilung-in-weitere-dateienabschnitte">Strukturierte Unterteilung in weitere Dateien/Abschnitte</a></li>
<li><a href="#übersichtlichkeit-und-navigierbarkeit" id="toc-übersichtlichkeit-und-navigierbarkeit" class="nav-link" data-scroll-target="#übersichtlichkeit-und-navigierbarkeit">Übersichtlichkeit und Navigierbarkeit</a></li>
<li><a href="#beispiele-codeblöcke-und-ggf.-abbildungen-einbinden" id="toc-beispiele-codeblöcke-und-ggf.-abbildungen-einbinden" class="nav-link" data-scroll-target="#beispiele-codeblöcke-und-ggf.-abbildungen-einbinden">Beispiele, Codeblöcke und ggf. Abbildungen einbinden</a></li>
<li><a href="#fazit-format-und-struktur" id="toc-fazit-format-und-struktur" class="nav-link" data-scroll-target="#fazit-format-und-struktur">Fazit Format und Struktur</a></li>
</ul></li>
<li><a href="#die-dokumentation-selbst" id="toc-die-dokumentation-selbst" class="nav-link" data-scroll-target="#die-dokumentation-selbst">Die Dokumentation selbst</a>
<ul class="collapse">
<li><a href="#umfang-und-fokus-der-dokumentation" id="toc-umfang-und-fokus-der-dokumentation" class="nav-link" data-scroll-target="#umfang-und-fokus-der-dokumentation">Umfang und Fokus der Dokumentation</a></li>
<li><a href="#priorisierung-bei-zeitmangel" id="toc-priorisierung-bei-zeitmangel" class="nav-link" data-scroll-target="#priorisierung-bei-zeitmangel">Priorisierung bei Zeitmangel</a></li>
</ul></li>
<li><a href="#was-macht-eine-gute-dokumentation-aus" id="toc-was-macht-eine-gute-dokumentation-aus" class="nav-link" data-scroll-target="#was-macht-eine-gute-dokumentation-aus">Was macht eine gute Dokumentation aus</a>
<ul class="collapse">
<li><a href="#formelle-prinzipien-open-source-research-fair4rs-und-endings" id="toc-formelle-prinzipien-open-source-research-fair4rs-und-endings" class="nav-link" data-scroll-target="#formelle-prinzipien-open-source-research-fair4rs-und-endings">Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS</a></li>
<li><a href="#nutzungshilfen-außerhalb-der-dokumentation" id="toc-nutzungshilfen-außerhalb-der-dokumentation" class="nav-link" data-scroll-target="#nutzungshilfen-außerhalb-der-dokumentation">Nutzungshilfen außerhalb der Dokumentation</a></li>
<li><a href="#prinzipien-fair-und-endings" id="toc-prinzipien-fair-und-endings" class="nav-link" data-scroll-target="#prinzipien-fair-und-endings">Prinzipien: FAIR und ENDINGS</a></li>
<li><a href="#kontinuierliche-verbesserung-und-feedback" id="toc-kontinuierliche-verbesserung-und-feedback" class="nav-link" data-scroll-target="#kontinuierliche-verbesserung-und-feedback">Kontinuierliche Verbesserung und Feedback</a></li>
<li><a href="#positiv--und-negativbeispiele-studieren" id="toc-positiv--und-negativbeispiele-studieren" class="nav-link" data-scroll-target="#positiv--und-negativbeispiele-studieren">Positiv- und Negativbeispiele studieren</a></li>
</ul></li>
@ -2263,11 +2231,11 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<li><a href="#docstrings-und-api-dokumentationsgeneratoren" id="toc-docstrings-und-api-dokumentationsgeneratoren" class="nav-link" data-scroll-target="#docstrings-und-api-dokumentationsgeneratoren">Docstrings und API-Dokumentationsgeneratoren</a></li>
<li><a href="#versionskontrolle-und-kontinuierliche-dokumentationspflege" id="toc-versionskontrolle-und-kontinuierliche-dokumentationspflege" class="nav-link" data-scroll-target="#versionskontrolle-und-kontinuierliche-dokumentationspflege">Versionskontrolle und kontinuierliche Dokumentationspflege</a></li>
</ul></li>
<li><a href="#best-practices-vorlagen-und-checklisten" id="toc-best-practices-vorlagen-und-checklisten" class="nav-link" data-scroll-target="#best-practices-vorlagen-und-checklisten">Best Practices, Vorlagen und Checklisten</a>
<li><a href="#checklisten-und-vorlagen" id="toc-checklisten-und-vorlagen" class="nav-link" data-scroll-target="#checklisten-und-vorlagen">Checklisten und Vorlagen</a>
<ul class="collapse">
<li><a href="#checkliste-für-die-mindest-dokumentation" id="toc-checkliste-für-die-mindest-dokumentation" class="nav-link" data-scroll-target="#checkliste-für-die-mindest-dokumentation">Checkliste für die Mindest-Dokumentation</a></li>
</ul></li>
<li><a href="#implementierung-aller-vorschläge-als-ready-to-use-repository" id="toc-implementierung-aller-vorschläge-als-ready-to-use-repository" class="nav-link" data-scroll-target="#implementierung-aller-vorschläge-als-ready-to-use-repository">Implementierung aller Vorschläge als ready-to-use Repository</a></li>
</ul></li>
<li><a href="#fazit" id="toc-fazit" class="nav-link" data-scroll-target="#fazit">Fazit</a></li>
@ -2344,16 +2312,16 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<section id="einleitung" class="level2">
<h2 class="anchored" data-anchor-id="einleitung">Einleitung</h2>
<p>Die <strong>Dokumentation von Forschungssoftware</strong> ist entscheidend, um wissenschaftliche Ergebnisse nachvollziehbar und Software für andere nutzbar zu machen. Insbesondere in den Digital Humanities (etwa in der Geschichtswissenschaft) entwickeln Forschende neben Forschung und Lehre oft eigene Software – meist unter hohem Zeitdruck und ohne formale Ausbildung in Softwareentwicklung. Häufig bleibt die Dokumentation deshalb minimal oder unvollständig, was dazu führt, dass andere (und sogar die Autor*innen selbst) viel Zeit aufwenden müssen, um den Code zu verstehen und anzuwenden. Dabei gilt gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware <strong>auffindbar, nachvollziehbar und wiederverwendbar</strong> zu machen.</p>
<p>Dieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll <strong>wissenschaftlich fundierte Richtlinien</strong> für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering (RSE) und damit einhergehender Prinzipien wie die des <em>Endings-Projekts</em> für digitale Langlebigkeit <span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> und <em>FAIR-Prinzipien</em> für Software<span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">2</a>]</span>.</p>
<p>Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die <strong>Nachvollziehbarkeit</strong> der Ergebnisse als auch eine <strong>Weiterverwendung</strong> der Software zu ermöglichen<span class="citation" data-cites="WilsonEtAl2017Goodenoughpractices">[<a href="#ref-WilsonEtAl2017Goodenoughpractices" role="doc-biblioref">3</a>]</span>.</p>
<p>Dieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll <strong>wissenschaftlich fundierte Richtlinien</strong> für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering <a href="@Hasselbring2020OpenSourceResearch;%20@Lee2018Tensimplerules">RSE</a> und damit einhergehender Prinzipien wie die des <em>Endings-Projekts</em> für digitale Langlebigkeit <span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> und <em>FAIR4RS-Prinzipien</em><span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">2</a>]</span>.</p>
<p>Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die <strong>Nachvollziehbarkeit</strong> der Ergebnisse als auch eine <strong>Weiterverwendung</strong> der Software zu ermöglichen<span class="citation" data-cites="Wilson2017GoodEnoughPractices">[<a href="#ref-Wilson2017GoodEnoughPractices" role="doc-biblioref">3</a>]</span>.</p>
<p>Im Folgenden werden die Anforderungen an Inhalt, Format und Umfang der Dokumentation definiert, geeignete (teil-)automatisierte Dokumentationswerkzeuge diskutiert und Best Practices in Form von Vorlagen und Checklisten vorgestellt.</p>
</section>
<section id="inhaltliche-anforderungen-an-die-dokumentation" class="level2 page-columns page-full">
<h2 class="anchored" data-anchor-id="inhaltliche-anforderungen-an-die-dokumentation">Inhaltliche Anforderungen an die Dokumentation</h2>
<p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="lamprecht2020towards">[<a href="#ref-lamprecht2020towards" role="doc-biblioref">4</a>]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
<section id="ziel-und-zweck-der-software-statement-of-need" class="level3">
<p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="EndingsPrinciples221 Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>, <a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">4</a>]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
<section id="ziel-und-zweck-der-software-statement-of-need" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="ziel-und-zweck-der-software-statement-of-need">Ziel und Zweck der Software (Statement of Need)</h3>
<p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em> Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).</p>
<div class="page-columns page-full"><p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em></span></div></div>
</section>
<section id="input-output-spezifikation-und-datenbeschreibung" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="input-output-spezifikation-und-datenbeschreibung">Input-/Output-Spezifikation und Datenbeschreibung</h3>
@ -2365,54 +2333,23 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<section id="code-abhängigkeiten-und-technische-voraussetzungen" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="code-abhängigkeiten-und-technische-voraussetzungen">Code-Abhängigkeiten und technische Voraussetzungen</h3>
<div class="page-columns page-full"><p>Listen Sie alle <em>Abhängigkeiten</em> (Dependencies) der Software auf. Dazu gehören verwendete Programmiersprachen/Versionen, erforderliche Bibliotheken oder Frameworks, und sonstige Systemvoraussetzungen (z. B. Betriebssystem, Mindesthardware, Datenbank-Versionen). Wichtig ist, <strong>wie</strong> diese Abhängigkeiten installiert werden können. Optimal ist eine automatisierte Installationsroutine (z. B. ein <code>requirements.txt</code> für Python oder ein Paketmanager-Befehl). In jedem Fall sollte die Dokumentation mindestens Schritt-für-Schritt-Installationsanleitungen enthalten (inklusive evtl. benötigter Vorkenntnisse, z. B. <em>“Python 3 erforderlich”</em>). </p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation: <code>pip install -r requirements.txt</code>.”</em> Falls spezielle technische Voraussetzungen bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder große Speicherkapazitäten – sind diese zu nennen.</span></div></div>
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-tip callout-titled" title="Prinzip">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Prinzip
</div>
</div>
<div class="callout-body-container callout-body">
<p>Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.</p>
</div>
</div></div><div class="callout callout-style-default callout-note callout-titled" title="Typische Nutzungsszenarien und Workflows">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-2-contents" aria-controls="callout-2" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Typische Nutzungsszenarien und Workflows
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-2" class="callout-2-contents callout-collapse collapse">
<div class="callout-body-container callout-body">
<p>Zeigen Sie anhand von <em>Beispielen</em>, wie die Software benutzt wird. Ein <strong>Quickstart-Beispiel</strong> senkt die Einstiegshürde enorm. Dies kann z. B. eine Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum gewünschten Ergebnis kommt (<em>“Getting Started”</em>-Abschnitt).</p>
<p>Beschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf. können mehrere Anwendungsfälle skizziert werden (z. B. <em>“Analyse eines einzelnen Briefes”</em> vs. <em>“Batch-Verarbeitung eines gesamten Korpus”</em>).</p>
<p>Diese Beispiele sollten realistisch und möglichst <em>repräsentativ für wissenschaftliche Anwendungen</em> sein. Nutzen Sie gerne kleine Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei Kommandozeilentools, via <code>--help</code> dokumentiert).</p>
</div>
</div>
</div>
</section>
<section id="wissenschaftlicher-hintergrund-und-theoretischer-kontext" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="wissenschaftlicher-hintergrund-und-theoretischer-kontext">Wissenschaftlicher Hintergrund und theoretischer Kontext</h3>
<p>Da es sich um Forschungssoftware handelt, sollten Sie den <em>wissenschaftlichen Kontext</em> <a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.</p>
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”</em> Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p>
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><div class="page-columns page-full"><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”</em></span></div></div>
<p>Wichtig ist, dass die Dokumentation den <strong>Brückenschlag zwischen Code und Forschung</strong> herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.</p>
</section>
<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3">
<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="bekannte-limitationen-annahmen-und-fehlermeldungen">Bekannte Limitationen, Annahmen und Fehlermeldungen</h3>
<p>Geben Sie ehrlich Auskunft über die <em>Grenzen der Software</em>:</p>
<ul>
<li>Welche Fälle werden <strong>nicht</strong> abgedeckt?</li>
<li>Welche <strong>Annahmen</strong> über die Daten oder Anwendungsszenarien werden getroffen?</li>
</ul>
<p>Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. <em>“funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”</em>). Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.</p>
<div class="page-columns page-full"><p> Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispielsweise: <em>“funktioniert nur für Deutschsprachige Texte”</em> oder <em>“maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”</em></span></div></div>
<p>Falls es bekannte <strong>Bugs oder Workarounds</strong> gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.</p>
<p>Auch <strong>aussagekräftige Fehlermeldungen</strong> im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann (z. B. <em>“Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”</em>). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.</p>
<div class="page-columns page-full"><p>Auch <strong>aussagekräftige Fehlermeldungen</strong> im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann. Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”</em></span></div></div>
</section>
<section id="weiterentwicklung-und-beitragsmöglichkeiten" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="weiterentwicklung-und-beitragsmöglichkeiten">Weiterentwicklung und Beitragsmöglichkeiten</h3>
@ -2421,22 +2358,33 @@ Typische Nutzungsszenarien und Workflows
<div class="no-row-height column-margin column-container"><div id="fn2"><p><sup>2</sup> Dieser Aspekt muss nicht umfangreich sein, zeigt aber Offenheit und sorgt dafür, dass im Falle von Rückfragen die Hürde für Kontaktaufnahme niedrig ist.</p></div></div></section>
<section id="projekt-metadaten-lizenz-zitation-version" class="level3">
<h3 class="anchored" data-anchor-id="projekt-metadaten-lizenz-zitation-version">Projekt-Metadaten (Lizenz, Zitation, Version)</h3>
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten<span class="citation" data-cites="lamprecht2020towards">[<a href="#ref-lamprecht2020towards" role="doc-biblioref">4</a>]</span>. <strong>Lizenzinformationen</strong> klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine <strong>LICENSE-Datei</strong> beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.</p>
<p>Zudem sollte angegeben werden, wie die Software <strong>zitiert</strong> werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt <em>“Zitation”</em> oder eine <strong>CITATION-Datei</strong> beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen <span class="citation" data-cites="NoyEtAl2019IndustryscaleKnowledge">[<a href="#ref-NoyEtAl2019IndustryscaleKnowledge" role="doc-biblioref">5</a>]</span>.</p>
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten<span class="citation" data-cites="Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">4</a>]</span>. <strong>Lizenzinformationen</strong> klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine <strong>LICENSE-Datei</strong> beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.</p>
<p>Zudem sollte angegeben werden, wie die Software <strong>zitiert</strong> werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt <em>“Zitation”</em> oder eine <strong>CITATION-Datei</strong> beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen <span class="citation" data-cites="Smith2016SoftwareCitationPrinciples">[<a href="#ref-Smith2016SoftwareCitationPrinciples" role="doc-biblioref">5</a>]</span>.</p>
<p>Schließlich ist es sinnvoll, eine <strong>Versionsnummer</strong> der Software zu nennen (idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen gibt<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span>.</p>
</section>
<section id="zusammenfassung-der-inhaltlichen-anforderungen" class="level3">
<h3 class="anchored" data-anchor-id="zusammenfassung-der-inhaltlichen-anforderungen">Zusammenfassung der inhaltlichen Anforderungen</h3>
<p>Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantworten:</p>
<ul>
<li><em>Was</em> tut die Software,</li>
<li><em>warum</em> wurde sie geschrieben (wissenschaftlicher Zweck),</li>
<li><em>wer</em> soll sie nutzen,</li>
<li><em>wie</em> wird sie benutzt (Inputs, Outputs, Abläufe),</li>
<li><em>womit</em> läuft sie (Umgebung/Abhängigkeiten),</li>
<li><em>unter welchen Bedingungen</em> (Annahmen/Limitationen) und</li>
<li><em>wohin</em> können sich Nutzer wenden (Support/Zitation).</li>
<div class="callout callout-style-default callout-important callout-titled" title="Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantworten
</div>
</div>
<div class="callout-body-container callout-body">
<ul class="task-list">
<li><label><input type="checkbox"><em>Was</em> tut die Software,</label></li>
<li><label><input type="checkbox"><em>warum</em> wurde sie geschrieben (wissenschaftlicher Zweck),</label></li>
<li><label><input type="checkbox"><em>wer</em> soll sie nutzen,</label></li>
<li><label><input type="checkbox"><em>wie</em> wird sie benutzt (Inputs, Outputs, Abläufe),</label></li>
<li><label><input type="checkbox"><em>womit</em> läuft sie (Umgebung/Abhängigkeiten),</label></li>
<li><label><input type="checkbox"><em>unter welchen Bedingungen</em> (Annahmen/Limitationen) und</label></li>
<li><label><input type="checkbox"><em>wohin</em> können sich Nutzer wenden (Support/Zitation).</label></li>
</ul>
</div>
</div>
<p>All diese Punkte sorgen für <strong>Nachvollziehbarkeit</strong> (im Sinne von Reproduzierbarkeit der Ergebnisse) und <strong>Weiterverwendbarkeit</strong> (im Sinne von Adaptierbarkeit der Software für neue Kontexte).</p>
</section>
</section>
@ -2504,7 +2452,7 @@ Prinzip
<li><code>LICENSE</code> – Lizenztext</li>
<li><code>CITATION.cff</code> oder <code>CITATION.md</code> – wie zu zitieren.</li>
</ul>
<p>Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie leicht auffindbar sind.</p>
<p>Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie leicht auffindbar und ggf. direkt durch Tools verarbeitbar sind.</p>
</section>
<section id="übersichtlichkeit-und-navigierbarkeit" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="übersichtlichkeit-und-navigierbarkeit">Übersichtlichkeit und Navigierbarkeit</h3>
@ -2526,23 +2474,41 @@ Prinzip
</section>
<section id="beispiele-codeblöcke-und-ggf.-abbildungen-einbinden" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="beispiele-codeblöcke-und-ggf.-abbildungen-einbinden">Beispiele, Codeblöcke und ggf. Abbildungen einbinden</h3>
<p>Nutzen Sie die Möglichkeiten von <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>, um die Dokumentation lebendig zu gestalten. Zeigen Sie Code-Beispiele als formatierte Codeblöcke, fügen Sie Links zu weiterführenden Ressourcen ein, oder binden Sie bei Bedarf Abbildungen ein (etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche, etc.).</p>
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-tip callout-titled" title="Prinzip">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Prinzip
</div>
</div>
<div class="callout-body-container callout-body">
<p>Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.</p>
</div>
</div></div><p>Nutzen Sie die Möglichkeiten von <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>, um die Dokumentation lebendig zu gestalten. Zeigen Sie Code-Beispiele als formatierte Codeblöcke, fügen Sie Links zu weiterführenden Ressourcen ein, oder binden Sie bei Bedarf Abbildungen ein (etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche, etc.).</p>
<p>Achten Sie dabei auf Dateigrößen und Formate (Bilder als PNG/JPG, Diagramme wenn möglich als SVG für Langlebigkeit). Falls Diagramme der Architektur oder Workflow-Abbildungen hilfreich sind, können diese mit simplen Mitteln erstellt werden<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>.</p>
<div class="no-row-height column-margin column-container"><div id="fn3"><p><sup>3</sup> zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie <a href="https://mermaid.js.org/" title="Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden">mermaid.js</a> Diagrammen in <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> oder <a href="https://graphviz.org/" title="Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg">graphviz</a></p></div></div><p>Diese Visualisierungen sind jedoch nur dann einzusetzen, wenn sie echten Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im Zweifel hat textuelle Beschreibung Vorrang, um nicht vom <strong>Prinzip “keep it simple”</strong> abzuweichen.</p>
<div class="callout callout-style-default callout-note callout-titled" title="Typische Nutzungsszenarien und Workflows">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Typische Nutzungsszenarien und Workflows
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-5" class="callout-5-contents callout-collapse collapse">
<div class="callout-body-container callout-body">
<p>Zeigen Sie anhand von <em>konkreten Beispielen</em>, wie die Software benutzt wird. Ein <strong>Quickstart-Beispiel</strong> senkt die Einstiegshürde enorm. Dies kann z. B. eine Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum gewünschten Ergebnis kommt.</p>
<p>Beschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf. können mehrere Anwendungsfälle skizziert werden (z. B. <em>“Analyse eines einzelnen Briefes”</em> vs. <em>“Batch-Verarbeitung eines gesamten Korpus”</em>).</p>
<p>Diese Beispiele sollten realistisch und möglichst <em>repräsentativ für wissenschaftliche Anwendungen</em> sein. Nutzen Sie gerne kleine, mitgelieferte Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei Kommandozeilentools, via <code>--help</code> dokumentiert).</p>
</div>
</div>
</div>
</section>
<section id="fazit-format-und-struktur" class="level3">
<h3 class="anchored" data-anchor-id="fazit-format-und-struktur">Fazit Format und Struktur</h3>
<p>Insgesamt gilt: Die Dokumentation sollte</p>
<ul>
<li>im gleichen Repository leben wie der Code</li>
<li>klar strukturiert und in einem einfach handhabbaren Format vorliegen</li>
<li>ohne spezielle Umgebung lesbar sein</li>
</ul>
</section>
</section>
<section id="die-dokumentation-selbst" class="level2 page-columns page-full">
<h2 class="anchored" data-anchor-id="die-dokumentation-selbst">Die Dokumentation selbst</h2>
<p>Gerade weil Forschende wenig Zeit haben, muss die Dokumentation <strong>effizient</strong> gestaltet sein. Für typische Forschungssoftware-Projekte in den Geisteswissenschaften wird ein Umfang von <em>maximal ca. 10 Seiten</em> (bei Bedarf verteilt auf mehrere Dateien) als ausreichend erachtet.</p>
<section id="umfang-und-fokus-der-dokumentation" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="umfang-und-fokus-der-dokumentation">Umfang und Fokus der Dokumentation</h3>
@ -2593,15 +2559,15 @@ Prinzip
<li>Wie kann ich beitragen?</li>
<li>Wie funktioniert es unter der Haube?</li>
</ul>
<p>Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für Entwickler*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwickler*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code gut zu kommentieren und eventuell eine grobe Architekturübersicht bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, <strong>das Nutzen und Verstehen der Software von außen</strong> zu ermöglichen.</p>
<p>Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse. Konzentrieren Sie die Hauptdokumentation darauf, <strong>das Nutzen und Verstehen der Software von außen</strong> zu ermöglichen.</p>
</section>
</section>
<section id="priorisierung-bei-zeitmangel" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="priorisierung-bei-zeitmangel">Priorisierung bei Zeitmangel</h3>
<p>Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwickler*innendokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern nötig, um den Hauptnutzerfluss nicht zu überfrachten.</p>
<p>Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwickler*innendokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, oder sogar automatisch erzeugt werden.</p>
<section id="minimaldokumentation-kurze-kommentare" class="level4">
<h4 class="anchored" data-anchor-id="minimaldokumentation-kurze-kommentare">Minimaldokumentation: kurze Kommentare</h4>
<p>Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (<em>“keine Dokumentation”</em> ist keine Option). <em>Good Enough Practices</em><span class="citation" data-cites="WilsonEtAl2017Goodenoughpractices">[<a href="#ref-WilsonEtAl2017Goodenoughpractices" role="doc-biblioref">3</a>]</span> empfehlen, als ersten Schritt zumindest einen <strong>kurzen erklärenden Kommentar am Anfang jedes Scripts</strong> oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. Später kann die Dokumentation erweitert werden, insbesondere wenn die Software in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B. durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst <em>klein</em> anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte 30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).</p>
<p>Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (<em>“keine Dokumentation”</em> ist keine Option). <em>Good Enough Practices</em><span class="citation" data-cites="Wilson2017GoodEnoughPractices">[<a href="#ref-Wilson2017GoodEnoughPractices" role="doc-biblioref">3</a>]</span> empfehlen, als ersten Schritt zumindest einen <strong>kurzen erklärenden Kommentar am Anfang jedes Scripts</strong> oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. Später kann die Dokumentation erweitert werden, insbesondere wenn die Software in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B. durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst <em>klein</em> anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte 30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).</p>
</section>
<section id="verlinkte-dokumentation-ist-auch-dokumentation" class="level4">
<h4 class="anchored" data-anchor-id="verlinkte-dokumentation-ist-auch-dokumentation">Verlinkte Dokumentation ist auch Dokumentation</h4>
@ -2615,16 +2581,23 @@ Prinzip
</section>
<section id="was-macht-eine-gute-dokumentation-aus" class="level2 page-columns page-full">
<h2 class="anchored" data-anchor-id="was-macht-eine-gute-dokumentation-aus">Was macht eine gute Dokumentation aus</h2>
<section id="nutzungshilfen-außerhalb-der-dokumentation" class="level3">
<h3 class="anchored" data-anchor-id="nutzungshilfen-außerhalb-der-dokumentation">Nutzungshilfen außerhalb der Dokumentation</h3>
<p>Falls Ihre Software ein <strong>Command-Line Interface (CLI)</strong> hat, stellen Sie sicher, dass eine eingebaute Hilfe vorhanden ist (z. B. Ausgabe bei <code>--help</code>). Viele Nutzer greifen zunächst darauf zurück. Dieses Hilfemenü sollte kurz erläutern, welche Subkommandos oder Optionen existieren. Moderne CLI-Frameworks generieren solche Hilfen oft automatisch aus Ihrem Code (z. B. <a href="https://docs.python.org/3/library/argparse.html" title="Der Argument-Parser der Python-Standardbibliothek">argparse</a> in Python erzeugen <code>--help</code>-Texte). Nutzen Sie das, um konsistente Infos zu garantieren.</p>
<p>Für <strong>GUI-Anwendungen</strong> sollten Tooltips, Hilfetexte in der Oberfläche oder zumindest ein kleiner <em>Help</em>-Abschnitt im Handbuch vorhanden sein. Diese eingebetteten Hilfen ersetzen keine ausführliche Dokumentation, aber sie senken die Schwelle für alltägliche Fragen.</p>
</section>
<section id="prinzipien-fair-und-endings" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="prinzipien-fair-und-endings">Prinzipien: FAIR und ENDINGS</h3>
<p>Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des <strong>Research Software Engineering</strong><span class="citation" data-cites="Hasselbring2020OpenSourceResearch">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">6</a>]</span> und den <strong>ENDINGS-Prinzipien</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> steht.</p>
<section id="formelle-prinzipien-open-source-research-fair4rs-und-endings" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="formelle-prinzipien-open-source-research-fair4rs-und-endings">Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS</h3>
<p>Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des <strong>Research Software Engineering</strong><span class="citation" data-cites="Hasselbring2020OpenSourceResearch">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">6</a>]</span> und den <strong>FAIR4RS-<span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">2</a>]</span></strong> bzw. <strong>ENDINGS-Prinzipien</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> steht.</p>
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-note callout-titled" title="ENDINGS-Prinzipien">
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-note callout-titled" title="FAIR4RS-Prinzipien für Software">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
FAIR4RS-Prinzipien für Software
</div>
</div>
<div class="callout-body-container callout-body">
<p>Die FAIR4RS-Prinzipien sind eine Anpassung der Ursprünglich nur für Daten gedachten FAIR-Prinzipien. Der Fokus liegt hier nicht auf Software selbst, sondern auf eine Nutzung von Software die ein Äquivalent zur Nutzung von FAIR-Daten darstellt.</p>
</div>
</div><div class="callout callout-style-default callout-note callout-titled" title="ENDINGS-Prinzipien">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
@ -2634,9 +2607,10 @@ ENDINGS-Prinzipien
</div>
</div>
<div class="callout-body-container callout-body">
<p>Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit. Unsere Empfehlungen, etwa ein statisches Markdown-README beizulegen, die Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu machen, setzen genau diese Vorgaben um.</p>
<p>Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit.</p>
</div>
</div></div><p>Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von</p>
</div></div>
<p>Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von</p>
<ul>
<li>Reproduzierbarkeit (Installation, Daten, Beispiele),</li>
<li>Offenheit (Lizenz, offene Formate) und</li>
@ -2644,6 +2618,11 @@ ENDINGS-Prinzipien
</ul>
<p>Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche Softwarepraxis.</p>
</section>
<section id="nutzungshilfen-außerhalb-der-dokumentation" class="level3">
<h3 class="anchored" data-anchor-id="nutzungshilfen-außerhalb-der-dokumentation">Nutzungshilfen außerhalb der Dokumentation</h3>
<p>Falls Ihre Software ein <strong>Command-Line Interface (CLI)</strong> hat, stellen Sie sicher, dass eine eingebaute Hilfe vorhanden ist (z. B. Ausgabe bei <code>--help</code>). Viele Nutzer greifen zunächst darauf zurück. Dieses Hilfemenü sollte kurz erläutern, welche Subkommandos oder Optionen existieren. Moderne CLI-Frameworks generieren solche Hilfen oft automatisch aus Ihrem Code (z. B. <a href="https://docs.python.org/3/library/argparse.html" title="Der Argument-Parser der Python-Standardbibliothek">argparse</a> in Python erzeugen <code>--help</code>-Texte). Nutzen Sie das, um konsistente Infos zu garantieren.</p>
<p>Für <strong>GUI-Anwendungen</strong> sollten Tooltips, Hilfetexte in der Oberfläche oder zumindest ein kleiner <em>Help</em>-Abschnitt im Handbuch vorhanden sein. Diese eingebetteten Hilfen ersetzen keine ausführliche Dokumentation, aber sie senken die Schwelle für alltägliche Fragen.</p>
</section>
<section id="kontinuierliche-verbesserung-und-feedback" class="level3">
<h3 class="anchored" data-anchor-id="kontinuierliche-verbesserung-und-feedback">Kontinuierliche Verbesserung und Feedback</h3>
<p>Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:</p>
@ -2731,7 +2710,7 @@ Prinzip
</div>
</div><div id="fn5"><p><sup>5</sup> kurz für: “Documentation String”</p></div></div><p>Nutzen Sie die Möglichkeit, Dokumentation <em>direkt im Quellcode</em> unterzubringen, z. B. in Form von <strong>Docstrings<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a></strong> (mehrzeilige Strings in Funktionen/Klassen bei Python, <a href="https://roxygen2.r-lib.org/" title="Generator um aus R Docstrings eine Dokumentation zu generieren">Roxygen</a>-Kommentare in R, <a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a>-Kommentare in Java, etc.).</p>
<p>Diese dienen doppelt: Zum einen erleichtern sie es Ihnen und Kollegen, den Code beim Lesen zu verstehen, zum anderen können sie von Tools ausgelesen und zu hübschen API-Dokumentationen verarbeitet werden. Idealerweise dokumentieren Sie <em>jede wichtige <strong>oder</strong> von außen sichtbare Funktion, Klasse oder Modul</em> mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.</p>
<p>Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. <a href="https://google.github.io/styleguide/">Google Style Guide</a> für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen). Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa <strong><a href="https://www.pylint.org/" title="Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.">pylint</a></strong>, können die Verwendung erzwingen.</p>
<p>Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. <a href="https://google.github.io/styleguide/">Google Style Guide</a> für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)<span class="citation" data-cites="JimenezEtAl2017FourSimpleRecommendations">[<a href="#ref-JimenezEtAl2017FourSimpleRecommendations" role="doc-biblioref">8</a>]</span>. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa <strong><a href="https://www.pylint.org/" title="Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.">pylint</a></strong>, können die Verwendung erzwingen.</p>
<p>Mit Tools, wie <strong><a href="https://www.sphinx-doc.org" title="Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.">Sphinx</a></strong>, <strong><a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a></strong>, <strong><a href="https://www.doxygen.nl/" title="Generator um aus C/C++ Docstrings eine Dokumentation zu generieren">Doxygen</a></strong>, <strong><a href="https://www.mkdocs.org/" title="Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown">MkDocs</a></strong>,<strong><a href="https://pdoc.dev/" title="Generator um aus Python Docstrings eine Dokumentation zu generieren">pdoc</a></strong> und vielen weiteren, können aus Docstrings automatisiert Webseiten oder PDF-Handbücher generiert werden. Sie lesen z. B. die Python-Docstrings und erzeuge daraus strukturiert eine Dokumentation; Häufig kann über Erweiterungen auch dritte Dokumentation direkt eingebunden und verlinkt werden.</p>
</section>
<section id="versionskontrolle-und-kontinuierliche-dokumentationspflege" class="level3 page-columns page-full">
@ -2753,8 +2732,8 @@ Prinzip
<p>Schlussendlich muss aber das Level an Automation für jedes Projekt individuell abgewogen werden.</p>
</section>
</section>
<section id="best-practices-vorlagen-und-checklisten" class="level2">
<h2 class="anchored" data-anchor-id="best-practices-vorlagen-und-checklisten">Best Practices, Vorlagen und Checklisten</h2>
<section id="checklisten-und-vorlagen" class="level2">
<h2 class="anchored" data-anchor-id="checklisten-und-vorlagen">Checklisten und Vorlagen</h2>
<p>Um zu entscheiden, <em>was</em> dokumentiert wird (und was <em>nicht</em>), helfen etablierte <strong>Best Practices</strong> sowie Vorlagen aus der Community. Im Folgenden sind einige bewährte Richtlinien zusammengefasst.</p>
<section id="checkliste-für-die-mindest-dokumentation" class="level3">
<h3 class="anchored" data-anchor-id="checkliste-für-die-mindest-dokumentation">Checkliste für die Mindest-Dokumentation</h3>
@ -2773,9 +2752,8 @@ Prinzip
</ol>
<p>Diese Checkliste kann vor einem “Release” der Software durchgegangen werden, ähnlich einem Review-Prozess (vgl. <a href="https://joss.readthedocs.io/en/latest/review_checklist.html">JOSS Review-Kriterien</a>, die viele dieser Punkte abdecken). Sie hilft zu entscheiden, was noch dokumentiert werden muss und was eventuell weggelassen werden kann. <strong>Alles, was für die obigen Punkte nicht relevant ist, kann man tendenziell aus der Hauptdokumentation herauslassen.</strong></p>
</section>
</section>
<section id="implementierung-aller-vorschläge-als-ready-to-use-repository" class="level2">
<h2 class="anchored" data-anchor-id="implementierung-aller-vorschläge-als-ready-to-use-repository">Implementierung aller Vorschläge als ready-to-use Repository</h2>
<section id="implementierung-aller-vorschläge-als-ready-to-use-repository" class="level3">
<h3 class="anchored" data-anchor-id="implementierung-aller-vorschläge-als-ready-to-use-repository">Implementierung aller Vorschläge als ready-to-use Repository</h3>
<div class="callout callout-style-default callout-important callout-titled" title="TODO">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
@ -2793,11 +2771,12 @@ TODO
</div>
</div>
</section>
</section>
<section id="fazit" class="level2">
<h2 class="anchored" data-anchor-id="fazit">Fazit</h2>
<p>Die hier präsentierten Anforderungen und Empfehlungen bieten einen <strong>Leitfaden für die Dokumentation von Forschungssoftware</strong> in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale <strong>Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit</strong> zu erreichen.</p>
<p>Indem zentrale Inhalte (Ziele, Inputs/Outputs, Hintergrund, etc.) klar dokumentiert, ein nutzerfreundliches Format (README im Repo) gewählt, der Umfang fokussiert gehalten und hilfreiche Tools eingesetzt werden, kann die Dokumentation zur Stärke eines Projekts werden statt einem lästigen Anhängsel.</p>
<p>So schließt sich der Kreis zwischen guter <strong>Softwareentwicklung</strong> und guter <strong>Wissenschaft</strong><span class="citation" data-cites="Forschungsgemeinschaft2025LeitlinienzurSicherung">[<a href="#ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" role="doc-biblioref">8</a>, Leitlinie 12]</span>: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch wie die Erfahrung zeigt, zahlen sich diese in Form von <em>Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung</em> der Software aus. Mit diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen – trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: <strong>Gut dokumentierte Forschungscode ist nachhaltige Forschung</strong>.</p>
<p>So schließt sich der Kreis zwischen guter <strong>Softwareentwicklung</strong> und guter <strong>Wissenschaft</strong><span class="citation" data-cites="Forschungsgemeinschaft2025LeitlinienzurSicherung">[<a href="#ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" role="doc-biblioref">9</a>, Leitlinie 12]</span>: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch wie die Erfahrung zeigt, zahlen sich diese in Form von <em>Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung</em> der Software aus. Mit diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen – trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: <strong>Gut dokumentierte Forschungscode ist nachhaltige Forschung</strong>.</p>
</section>
@ -2908,7 +2887,7 @@ TODO
<li><a href="https://en.wikipedia.org/wiki/ReStructuredText" title="Alternative zu Markdown.">rst</a>: Alternative zu Markdown.</li>
<li><a href="https://www.sphinx-doc.org" title="Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.">Sphinx</a>: Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.</li>
</ul>
</div></section><section id="bibliographie" class="level2 unnumbered appendix column-page"><h2 class="quarto-appendix-heading"></h2><div class="quarto-appendix-contents">
</div></section><section id="bibliographie" class="level2 unnumbered appendix"><h2 class="quarto-appendix-heading"></h2><div class="quarto-appendix-contents">
</div></section><section class="quarto-appendix-contents" role="doc-bibliography" id="quarto-bibliography"><h2 class="anchored quarto-appendix-heading">Bibliographie</h2><div id="refs" class="references csl-bib-body" data-entry-spacing="0" role="list">
@ -2918,13 +2897,13 @@ TODO
<div id="ref-BarkerEtAl2022IntroducingFAIR" class="csl-entry" role="listitem">
<div class="csl-left-margin">2. </div><div class="csl-right-inline">Barker, Michelle, Neil P. Chue Hong, Daniel S. Katz, Anna-Lena Lamprecht, Carlos Martinez-Ortiz, Fotis Psomopoulos, Jennifer Harrow, u. a. 2022. Introducing the <span>FAIR Principles</span> for Research Software. <em>Scientific Data</em> 9. Nature Publishing Group: 622. <a href="https://doi.org/10.1038/s41597-022-01710-x">https://doi.org/10.1038/s41597-022-01710-x</a>.</div>
</div>
<div id="ref-WilsonEtAl2017Goodenoughpractices" class="csl-entry" role="listitem">
<div id="ref-Wilson2017GoodEnoughPractices" class="csl-entry" role="listitem">
<div class="csl-left-margin">3. </div><div class="csl-right-inline">Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. <em>PLOS Computational Biology</em> 13. Public Library of Science: e1005510. <a href="https://doi.org/10.1371/journal.pcbi.1005510">https://doi.org/10.1371/journal.pcbi.1005510</a>.</div>
</div>
<div id="ref-lamprecht2020towards" class="csl-entry" role="listitem">
<div id="ref-Lamprecht2020TowardsFAIRPrinciples" class="csl-entry" role="listitem">
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards <span>FAIR</span> Principles for Research Software. <em>Data Science</em> 3. SAGE Publications: 37–59. <a href="https://doi.org/10.3233/DS-190026">https://doi.org/10.3233/DS-190026</a>.</div>
</div>
<div id="ref-NoyEtAl2019IndustryscaleKnowledge" class="csl-entry" role="listitem">
<div id="ref-Smith2016SoftwareCitationPrinciples" class="csl-entry" role="listitem">
<div class="csl-left-margin">5. </div><div class="csl-right-inline">Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. <em>PeerJ Computer Science</em> 2. PeerJ Inc. <a href="https://doi.org/10.7717/peerj-cs.86">https://doi.org/10.7717/peerj-cs.86</a>.</div>
</div>
<div id="ref-Hasselbring2020OpenSourceResearch" class="csl-entry" role="listitem">
@ -2933,8 +2912,11 @@ TODO
<div id="ref-KluyverEtAl2016JupyterNotebookspublishing" class="csl-entry" role="listitem">
<div class="csl-left-margin">7. </div><div class="csl-right-inline">Kluyver, Thomas, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, u. a. 2016. Jupyter <span>Notebooks</span> – a Publishing Format for Reproducible Computational Workflows. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. <a href="https://doi.org/10.3233/978-1-61499-649-1-87">https://doi.org/10.3233/978-1-61499-649-1-87</a>.</div>
</div>
<div id="ref-JimenezEtAl2017FourSimpleRecommendations" class="csl-entry" role="listitem">
<div class="csl-left-margin">8. </div><div class="csl-right-inline">Jiménez, Rafael C., Mateusz Kuzak, Monther Alhamdoosh, Michelle Barker, Bérénice Batut, Mikael Borg, Salvador Capella-Gutierrez, u. a. 2017. Four Simple Recommendations to Encourage Best Practices in Research Software. <em>F1000Research</em> 6: 876. <a href="https://doi.org/10.12688/f1000research.11407.1">https://doi.org/10.12688/f1000research.11407.1</a>.</div>
</div>
<div id="ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" class="csl-entry" role="listitem">
<div class="csl-left-margin">8. </div><div class="csl-right-inline"><em>Leitlinien zur Sicherung guter wissenschaftlicher Praxis</em>. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. <a href="https://doi.org/10.5281/zenodo.14281892">https://doi.org/10.5281/zenodo.14281892</a>.</div>
<div class="csl-left-margin">9. </div><div class="csl-right-inline"><em>Leitlinien zur Sicherung guter wissenschaftlicher Praxis</em>. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. <a href="https://doi.org/10.5281/zenodo.14281892">https://doi.org/10.5281/zenodo.14281892</a>.</div>
</div>
</div></section><section class="quarto-appendix-contents" id="quarto-citation"><h2 class="anchored quarto-appendix-heading">Zitat</h2><div><div class="quarto-appendix-secondary-label">Mit BibTeX zitieren:</div><pre class="sourceCode code-with-copy quarto-appendix-bibtex"><code class="sourceCode bibtex">@online{dresselhaus2025,
author = {Dresselhaus, Nicole and deep research, GPT-4.5},

226
background/BACKGROUND.md
View File

@ -25,8 +25,8 @@ authors:
orcid: 0009-0008-8850-3679
roles:
- Conceptualization
- Supervision
- Investigation
- Supervision
- Validation
- "Writing – review & editing"
- name: GPT-4.5 "deep research"
@ -75,15 +75,16 @@ gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware
Dieser Anforderungskatalog richtet sich an Forschende, die keine
Vollzeit-Programmierer sind, und soll **wissenschaftlich fundierte Richtlinien**
für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen
berücksichtigen Best Practices des Research Software Engineering (RSE) und damit
berücksichtigen Best Practices des Research Software Engineering
[RSE](@Hasselbring2020OpenSourceResearch; @Lee2018Tensimplerules) und damit
einhergehender Prinzipien wie die des _Endings-Projekts_ für digitale
Langlebigkeit [@EndingsPrinciples221] und _FAIR-Prinzipien_ für
Software[@BarkerEtAl2022IntroducingFAIR].
Langlebigkeit [@EndingsPrinciples221] und
_FAIR4RS-Prinzipien_[@BarkerEtAl2022IntroducingFAIR].
Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz
Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die
**Nachvollziehbarkeit** der Ergebnisse als auch eine **Weiterverwendung** der
Software zu ermöglichen[@WilsonEtAl2017Goodenoughpractices].
Software zu ermöglichen[@Wilson2017GoodEnoughPractices].
Im Folgenden werden die Anforderungen an Inhalt, Format und Umfang der
Dokumentation definiert, geeignete (teil-)automatisierte Dokumentationswerkzeuge
@ -94,8 +95,9 @@ diskutiert und Best Practices in Form von Vorlagen und Checklisten vorgestellt.
Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft
das fehlende _Big Picture_, also eine klare Darstellung des _Was_ und _Warum_.
Die Dokumentation sollte daher alle **Informationen abdecken, die zum Verstehen,
Nutzen und Weiterentwickeln der Software nötig sind**[@lamprecht2020towards,
R1]. Insbesondere sind folgende Inhalte essenziell:
Nutzen und Weiterentwickeln der Software nötig sind**[@EndingsPrinciples221;
@Lamprecht2020TowardsFAIRPrinciples, R1]. Insbesondere sind folgende Inhalte
essenziell:
### Ziel und Zweck der Software (Statement of Need)
@ -103,12 +105,12 @@ Beschreiben Sie _was die Software tut_ und _warum sie entwickelt wurde_. Nennen
Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung,
die mit der Software adressiert wird, sowie die _Zielgruppe_ (wer soll sie
nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.
Beispiel: _“Dieses Tool extrahiert Personen-Netzwerke aus historischen
Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”_ Eine klare
Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher
Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die
eigene Herangehensweise einordnen (z. B. was die Software anders oder besser
macht).
[Beispiel: _“Dieses Tool extrahiert Personen-Netzwerke aus historischen
Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”_]{.aside}
Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld
ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die
Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software
anders oder besser macht).
### Input-/Output-Spezifikation und Datenbeschreibung
@ -150,33 +152,6 @@ _“Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation:
bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder
große Speicherkapazitäten – sind diese zu nennen.]{.aside}
::: {.callout-tip .column-margin title="Prinzip"}
Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.
:::
::: {.callout-note title="Typische Nutzungsszenarien und Workflows"
collapse="true"}
Zeigen Sie anhand von _Beispielen_, wie die Software benutzt wird. Ein
**Quickstart-Beispiel** senkt die Einstiegshürde enorm. Dies kann z. B. eine
Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum
gewünschten Ergebnis kommt (_“Getting Started”_-Abschnitt).
Beschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe
vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf.
können mehrere Anwendungsfälle skizziert werden (z. B. _“Analyse eines einzelnen
Briefes”_ vs. _“Batch-Verarbeitung eines gesamten Korpus”_).
Diese Beispiele sollten realistisch und möglichst _repräsentativ für
wissenschaftliche Anwendungen_ sein. Nutzen Sie gerne kleine Datensamples oder
Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können.
Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in
Form von Ausschnitten oder, bei Kommandozeilentools, via `--help` dokumentiert).
:::
### Wissenschaftlicher Hintergrund und theoretischer Kontext
Da es sich um Forschungssoftware handelt, sollten Sie den _wissenschaftlichen
@ -188,10 +163,10 @@ Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind,
zumindest in Überblicksform.
Verweisen Sie auf _relevante Publikationen_ oder Theorien, damit andere die
wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: _“Die
wissenschaftliche Grundlage nachvollziehen können. [Beispielsweise: _“Die
Implementierung folgt dem Algorithmus von Müller et al. (2019) zur
Netzwerkanalyse historischer Korrespondenz.”_ Halten Sie diesen Abschnitt aber
prägnant – Details gehören in die Forschungsarbeit selbst.
Netzwerkanalyse historischer Korrespondenz.”_]{.aside} Halten Sie diesen
Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.
Wichtig ist, dass die Dokumentation den **Brückenschlag zwischen Code und
Forschung** herstellt. Da viele Wissenschaftler\*innen zentrale Aspekte lieber
@ -206,10 +181,9 @@ Geben Sie ehrlich Auskunft über die _Grenzen der Software_:
- Welche Fälle werden **nicht** abgedeckt?
- Welche **Annahmen** über die Daten oder Anwendungsszenarien werden getroffen?
Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. _“funktioniert
nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da
Speicherbegrenzung”_). Solche Hinweise verhindern Fehlanwendungen und sparen
Nutzern Zeit.
[Beispielsweise: _“funktioniert nur für Deutschsprachige Texte”_ oder _“maximale
Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”_]{.aside} Solche Hinweise
verhindern Fehlanwendungen und sparen Nutzern Zeit.
Falls es bekannte **Bugs oder Workarounds** gibt, sollten diese ebenfalls (etwa
in einer FAQ oder einem Abschnitt "Bekannte Probleme") erwähnt werden.
@ -217,8 +191,8 @@ in einer FAQ oder einem Abschnitt "Bekannte Probleme") erwähnt werden.
Auch **aussagekräftige Fehlermeldungen** im Programm selbst sind eine Form von
Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der
Anwender\*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie
es behoben werden kann (z. B. _“Fehler: Ungültiges Datum im Feld XY – bitte
Format TT/MM/JJJJ verwenden.”_). Solche in den Code integrierten Hinweise
es behoben werden kann. [Beispiel: _“Fehler: Ungültiges Datum im Feld XY – bitte
Format TT/MM/JJJJ verwenden.”_]{.aside} Solche in den Code integrierten Hinweise
ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.
### Weiterentwicklung und Beitragsmöglichkeiten
@ -239,19 +213,19 @@ Kontaktaufnahme niedrig ist.]
### Projekt-Metadaten (Lizenz, Zitation, Version)
Teil der Dokumentation sind auch formale Informationen, die im Repository leicht
zugänglich sein sollten[@lamprecht2020towards]. **Lizenzinformationen** klären
die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best
Practice, eine **LICENSE-Datei** beizulegen, aber auch in der README kurz zu
erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware
empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code,
CC-BY für Daten), um Nachnutzung nicht zu behindern.
zugänglich sein sollten[@Lamprecht2020TowardsFAIRPrinciples].
**Lizenzinformationen** klären die rechtlichen Bedingungen der Nutzung und
Weiterverbreitung. Es ist Best Practice, eine **LICENSE-Datei** beizulegen, aber
auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht.
Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder
Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.
Zudem sollte angegeben werden, wie die Software **zitiert** werden kann (z. B.
DOI, Paper-Referenz). Ein eigener Abschnitt _“Zitation”_ oder eine
**CITATION-Datei** beschreibt, welche Publikation oder welcher DOI bei
Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies
erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor\*innen Credits
für ihre Software bekommen [@NoyEtAl2019IndustryscaleKnowledge].
für ihre Software bekommen [@Smith2016SoftwareCitationPrinciples].
Schließlich ist es sinnvoll, eine **Versionsnummer** der Software zu nennen
(idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche
@ -260,15 +234,18 @@ Aktualisierungen gibt[@EndingsPrinciples221].
### Zusammenfassung der inhaltlichen Anforderungen
Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten:
::: {.callout-important title="Zusammengefasst sollte die Dokumentation alle
**W-Fragen** beantworten"}
- _Was_ tut die Software,
- _warum_ wurde sie geschrieben (wissenschaftlicher Zweck),
- _wer_ soll sie nutzen,
- _wie_ wird sie benutzt (Inputs, Outputs, Abläufe),
- _womit_ läuft sie (Umgebung/Abhängigkeiten),
- _unter welchen Bedingungen_ (Annahmen/Limitationen) und
- _wohin_ können sich Nutzer wenden (Support/Zitation).
- [ ] _Was_ tut die Software,
- [ ] _warum_ wurde sie geschrieben (wissenschaftlicher Zweck),
- [ ] _wer_ soll sie nutzen,
- [ ] _wie_ wird sie benutzt (Inputs, Outputs, Abläufe),
- [ ] _womit_ läuft sie (Umgebung/Abhängigkeiten),
- [ ] _unter welchen Bedingungen_ (Annahmen/Limitationen) und
- [ ] _wohin_ können sich Nutzer wenden (Support/Zitation).
:::
All diese Punkte sorgen für **Nachvollziehbarkeit** (im Sinne von
Reproduzierbarkeit der Ergebnisse) und **Weiterverwendbarkeit** (im Sinne von
@ -368,7 +345,7 @@ Repository (z. B. eine `INSTALL.md` für ausführliche Installationshinweise,
- `CITATION.cff` oder `CITATION.md` – wie zu zitieren.
Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie
leicht auffindbar sind.
leicht auffindbar und ggf. direkt durch Tools verarbeitbar sind.
### Übersichtlichkeit und Navigierbarkeit
@ -393,6 +370,12 @@ Mantra _"Don’t Repeat Yourself"_ gilt auch für Dokumentation.
### Beispiele, Codeblöcke und ggf. Abbildungen einbinden
::: {.callout-tip .column-margin title="Prinzip"}
Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.
:::
Nutzen Sie die Möglichkeiten von [Markdown][], um die Dokumentation lebendig zu
gestalten. Zeigen Sie Code-Beispiele als formatierte Codeblöcke, fügen Sie Links
zu weiterführenden Ressourcen ein, oder binden Sie bei Bedarf Abbildungen ein
@ -410,20 +393,27 @@ Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im
Zweifel hat textuelle Beschreibung Vorrang, um nicht vom **Prinzip “keep it
simple”** abzuweichen.
### Fazit Format und Struktur
::: {.callout-note title="Typische Nutzungsszenarien und Workflows"
collapse="true"}
Insgesamt gilt: Die Dokumentation sollte
Zeigen Sie anhand von _konkreten Beispielen_, wie die Software benutzt wird. Ein
**Quickstart-Beispiel** senkt die Einstiegshürde enorm. Dies kann z. B. eine
Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum
gewünschten Ergebnis kommt.
- im gleichen Repository leben wie der Code
- klar strukturiert und in einem einfach handhabbaren Format vorliegen
- ohne spezielle Umgebung lesbar sein
Beschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe
vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf.
können mehrere Anwendungsfälle skizziert werden (z. B. _“Analyse eines einzelnen
Briefes”_ vs. _“Batch-Verarbeitung eines gesamten Korpus”_).
## Die Dokumentation selbst
Diese Beispiele sollten realistisch und möglichst _repräsentativ für
wissenschaftliche Anwendungen_ sein. Nutzen Sie gerne kleine, mitgelieferte
Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt
ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen
Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei
Kommandozeilentools, via `--help` dokumentiert).
Gerade weil Forschende wenig Zeit haben, muss die Dokumentation **effizient**
gestaltet sein. Für typische Forschungssoftware-Projekte in den
Geisteswissenschaften wird ein Umfang von _maximal ca. 10 Seiten_ (bei Bedarf
verteilt auf mehrere Dateien) als ausreichend erachtet.
:::
### Umfang und Fokus der Dokumentation
@ -486,27 +476,22 @@ _Entwicklende Personen_ fragen:
- Wie funktioniert es unter der Haube?
Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf
Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für
Entwickler\*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später
ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche
Entwickler\*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code
gut zu kommentieren und eventuell eine grobe Architekturübersicht
bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, **das Nutzen
und Verstehen der Software von außen** zu ermöglichen.
Zweck, Nutzung und Ergebnisse. Konzentrieren Sie die Hauptdokumentation darauf,
**das Nutzen und Verstehen der Software von außen** zu ermöglichen.
### Priorisierung bei Zeitmangel
Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für
die Autoren selbst, wenn sie das Tool später wieder anfassen).
Entwickler\*innendokumentation (z. B. detaillierte API-Dokumente,
Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern
nötig, um den Hauptnutzerfluss nicht zu überfrachten.
Code-Kommentare, technische Architektur) kann separat gehalten werden, oder
sogar automatisch erzeugt werden.
#### Minimaldokumentation: kurze Kommentare
Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt
(_“keine Dokumentation”_ ist keine Option). _Good Enough
Practices_[@WilsonEtAl2017Goodenoughpractices] empfehlen, als ersten Schritt
Practices_[@Wilson2017GoodEnoughPractices] empfehlen, als ersten Schritt
zumindest einen **kurzen erklärenden Kommentar am Anfang jedes Scripts** oder
eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt
bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert.
@ -536,6 +521,40 @@ nach und nach das folgende Kapitel umsetzen.
## Was macht eine gute Dokumentation aus
### Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS
Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
**FAIR4RS-[@BarkerEtAl2022IntroducingFAIR]** bzw.
**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.
::: {.callout-note .column-margin title="FAIR4RS-Prinzipien für Software"}
Die FAIR4RS-Prinzipien sind eine Anpassung der Ursprünglich nur für Daten
gedachten FAIR-Prinzipien. Der Fokus liegt hier nicht auf Software selbst,
sondern auf eine Nutzung von Software die ein Äquivalent zur Nutzung von
FAIR-Daten darstellt.
:::
::: {.callout-note .column-margin title="ENDINGS-Prinzipien"}
Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung
von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und
Zitierbarkeit.
:::
Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von
- Reproduzierbarkeit (Installation, Daten, Beispiele),
- Offenheit (Lizenz, offene Formate) und
- Nachhaltigkeit (Versionierung, Langlebigkeit der Doku).
Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie
automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche
Softwarepraxis.
### Nutzungshilfen außerhalb der Dokumentation
Falls Ihre Software ein **Command-Line Interface (CLI)** hat, stellen Sie
@ -551,32 +570,6 @@ zumindest ein kleiner _Help_-Abschnitt im Handbuch vorhanden sein. Diese
eingebetteten Hilfen ersetzen keine ausführliche Dokumentation, aber sie senken
die Schwelle für alltägliche Fragen.
### Prinzipien: FAIR und ENDINGS
Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.
::: {.callout-note .column-margin title="ENDINGS-Prinzipien"}
Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung
von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und
Zitierbarkeit. Unsere Empfehlungen, etwa ein statisches Markdown-README
beizulegen, die Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu
machen, setzen genau diese Vorgaben um.
:::
Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von
- Reproduzierbarkeit (Installation, Daten, Beispiele),
- Offenheit (Lizenz, offene Formate) und
- Nachhaltigkeit (Versionierung, Langlebigkeit der Doku).
Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie
automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche
Softwarepraxis.
### Kontinuierliche Verbesserung und Feedback
Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess.
@ -726,9 +719,10 @@ enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.
Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres
Ökosystems (z. B. [Google Style Guide](https://google.github.io/styleguide/) für
Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen).
Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie
etwa **[pylint][]**, können die Verwendung erzwingen.
Python Docstrings oder entsprechende Formatvorgaben für andere
Sprachen)[@JimenezEtAl2017FourSimpleRecommendations]. Verlinken sie diese
Styleguides in der README. Sogenannte Linting-Tools, wie etwa **[pylint][]**,
können die Verwendung erzwingen.
Mit Tools, wie **[Sphinx][]**, **[Javadoc][]**, **[Doxygen][]**,
**[MkDocs][]**,**[pdoc][]** und vielen weiteren, können aus Docstrings
@ -760,7 +754,7 @@ Codeversion immer eine aktuelle Doku hat_.
Schlussendlich muss aber das Level an Automation für jedes Projekt individuell
abgewogen werden.
## Best Practices, Vorlagen und Checklisten
## Checklisten und Vorlagen
Um zu entscheiden, _was_ dokumentiert wird (und was _nicht_), helfen etablierte
**Best Practices** sowie Vorlagen aus der Community. Im Folgenden sind einige
@ -819,7 +813,7 @@ dokumentiert werden muss und was eventuell weggelassen werden kann. **Alles, was
für die obigen Punkte nicht relevant ist, kann man tendenziell aus der
Hauptdokumentation herauslassen.**
## Implementierung aller Vorschläge als ready-to-use Repository
### Implementierung aller Vorschläge als ready-to-use Repository
::: {.callout-important title="TODO"}

659
background/background.bib
View File

@ -76,7 +76,7 @@
% == BibLateX quality report for CremerEtAl2024Projektmanagement:
% Missing required field 'author'
@article{DiehlEtAl2025JournalOpenSource,
@article{Diehl2025JournalOpenSource,
title = {The {{Journal}} of {{Open Source Software}} ({{JOSS}}): {{Bringing Open-Source Software Practices}} to the {{Scholarly Publishing Community}} for {{Authors}}, {{Reviewers}}, {{Editors}}, and {{Publishers}}},
shorttitle = {The {{Journal}} of {{Open Source Software}} ({{JOSS}})},
author = {Diehl, Patrick and Soneson, Charlotte and Kurchin, Rachel C. and Mounce, Ross and Katz, Daniel S.},
@ -96,7 +96,7 @@
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/G4T6JNUU/Diehl et al. - 2025 - The Journal of Open Source Software (JOSS) Bringing Open-Source Software Practices to the Scholarly.pdf}
}
% == BibLateX quality report for DiehlEtAl2025JournalOpenSource:
% == BibLateX quality report for Diehl2025JournalOpenSource:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.iastatedigitalpress.com")
@ -160,28 +160,26 @@
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("DOI.org (Crossref)")
@book{Kemman2021Trading,
title = {Trading {{Zones}} of {{Digital History}}},
author = {Kemman, Max},
date = {2021},
series = {Studies in {{Digital History}} and {{Hermeneutics}}},
number = {1},
publisher = {De Gruyter Oldenbourg},
location = {Berlin, Boston},
doi = {10.1515/9783110682106},
url = {https://www.degruyter.com/document/doi/10.1515/9783110682106/html},
urldate = {2021-09-23},
abstract = {Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.},
isbn = {978-3-11-068210-6},
@article{JimenezEtAl2017FourSimpleRecommendations,
title = {Four Simple Recommendations to Encourage Best Practices in Research Software},
author = {Jiménez, Rafael C. and Kuzak, Mateusz and Alhamdoosh, Monther and Barker, Michelle and Batut, Bérénice and Borg, Mikael and Capella-Gutierrez, Salvador and Chue Hong, Neil and Cook, Martin and Corpas, Manuel and Flannery, Madison and Garcia, Leyla and Gelpí, Josep Ll. and Gladman, Simon and Goble, Carole and González Ferreiro, Montserrat and Gonzalez-Beltran, Alejandra and Griffin, Philippa C. and Grüning, Björn and Hagberg, Jonas and Holub, Petr and Hooft, Rob and Ison, Jon and Katz, Daniel S. and Leskošek, Brane and López Gómez, Federico and Oliveira, Luis J. and Mellor, David and Mosbergen, Rowland and Mulder, Nicola and Perez-Riverol, Yasset and Pergl, Robert and Pichler, Horst and Pope, Bernard and Sanz, Ferran and Schneider, Maria V. and Stodden, Victoria and Suchecki, Radosław and Svobodová Vařeková, Radka and Talvik, Harry-Anton and Todorov, Ilian and Treloar, Andrew and Tyagi, Sonika and Van Gompel, Maarten and Vaughan, Daniel and Via, Allegra and Wang, Xiaochuan and Watson-Haigh, Nathan S. and Crouch, Steve},
date = {2017-06-13},
journaltitle = {F1000Research},
shortjournal = {F1000Res},
volume = {6},
pages = {876},
issn = {2046-1402},
doi = {10.12688/f1000research.11407.1},
url = {https://f1000research.com/articles/6-876/v1},
urldate = {2025-06-05},
abstract = {Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. This manuscript does not aim to propose new software development best practices, but rather to provide simple recommendations that encourage the adoption of existing best practices. Software development best practices promote better quality software, and better quality software improves the reproducibility and reusability of research. These recommendations are designed around Open Source values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent. This manuscript is aimed at developers, but also at organisations, projects, journals and funders that can increase the quality and sustainability of research software by encouraging the adoption of these recommendations.},
langid = {english},
language = {en},
pagetotal = {182},
keywords = {Digital History,Eintrag bereinigt,PDF (Dropbox),project: documentation,TH-MA-Bloomsbury},
file = {/home/drezil/Zotero/storage/ZS2QA2H6/Kemman - 2021 - Trading Zones of Digital History.pdf}
keywords = {Praxisregeln,project: documentation,Project: Methods Lab 🥼,Research Software Engineering},
file = {/home/drezil/Zotero/storage/86E3F4DV/Jiménez et al. - 2017 - Four simple recommendations to encourage best practices in research software.pdf}
}
% == BibLateX quality report for Kemman2021Trading:
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.degruyter.com")
% == BibLateX quality report for JimenezEtAl2017FourSimpleRecommendations:
% ? unused Library catalog ("DOI.org (Crossref)")
@inproceedings{KluyverEtAl2016JupyterNotebookspublishing,
title = {Jupyter {{Notebooks}} – a Publishing Format for Reproducible Computational Workflows},
@ -206,7 +204,7 @@
% Missing required field 'booktitle'
% ? unused Library catalog ("eprints.soton.ac.uk")
@article{lamprecht2020towards,
@article{Lamprecht2020TowardsFAIRPrinciples,
title = {Towards {{FAIR}} Principles for~Research~Software},
author = {Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and Dominguez Del Angel, Victoria and family=Sandt, given=Stephanie, prefix=van de, useprefix=true and Ison, Jon and Martinez, Paula Andrea and McQuilton, Peter and Valencia, Alfonso and Harrow, Jennifer and Psomopoulos, Fotis and Gelpi, Josep Ll. and Chue Hong, Neil and Goble, Carole and Capella-Gutierrez, Salvador},
date = {2020-06-12},
@ -225,7 +223,7 @@
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/CCXUNESS/Lamprecht et al. - 2020 - Towards FAIR principles for research software.pdf}
}
% == BibLateX quality report for lamprecht2020towards:
% == BibLateX quality report for Lamprecht2020TowardsFAIRPrinciples:
% Unexpected field 'publisher'
% ? unused Library catalog ("SAGE Journals")
@ -252,29 +250,6 @@
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")
@article{NoyEtAl2019IndustryscaleKnowledge,
title = {Software Citation Principles},
author = {Smith, Arfon M. and Katz, Daniel S. and Niemeyer, Kyle E.},
date = {2016},
journaltitle = {PeerJ Computer Science},
shortjournal = {PeerJ Comput. Sci.},
volume = {2},
publisher = {PeerJ Inc.},
issn = {2376-5992},
doi = {10.7717/peerj-cs.86},
url = {https://peerj.com/articles/cs-86},
urldate = {2020-09-11},
abstract = {Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.},
langid = {english},
language = {en},
keywords = {Eintrag bereinigt,PDF (Dropbox),project: documentation,Project: Methods Lab 🥼,Research Software Engineering},
annotation = {Keine weiteren Informationen gefunden},
file = {/home/drezil/Zotero/storage/XVF927LY/Smith et al. - 2016 - Software citation principles.pdf}
}
% == BibLateX quality report for NoyEtAl2019IndustryscaleKnowledge:
% Unexpected field 'publisher'
% ? unused Library catalog ("peerj.com")
@article{PrlicProcter2012TenSimpleRules,
title = {Ten {{Simple Rules}} for the {{Open Development}} of {{Scientific Software}}},
author = {Prlić, Andreas and Procter, James B.},
@ -299,263 +274,7 @@
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("PLoS Journals")
@article{WilsonEtAl2017Goodenoughpractices,
title = {Good Enough Practices in Scientific Computing},
author = {Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K.},
date = {2017-06-22},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {13},
number = {6},
pages = {e1005510},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1005510},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510},
urldate = {2025-05-15},
abstract = {Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don't know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.},
langid = {english},
language = {en},
keywords = {Computer software,Control systems,Data management,Metadata,Programming languages,project: documentation,Project: Methods Lab 🥼,Reproducibility,Software tools,Source code},
file = {/home/drezil/Zotero/storage/KWWLZBNY/Wilson et al. - 2017 - Good enough practices in scientific computing.pdf}
}
% == BibLateX quality report for WilsonEtAl2017Goodenoughpractices:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")
@book{AhnertEtAl2023CollaborativeHistoricalResearch,
title = {Collaborative {{Historical Research}} in the {{Age}} of {{Big Data}}: {{Lessons}} from an {{Interdisciplinary Project}}},
shorttitle = {Collaborative {{Historical Research}} in the {{Age}} of {{Big Data}}},
author = {Ahnert, Ruth and Griffin, Emma and Ridge, Mia and Tolfo, Giorgia},
date = {2023},
series = {Cambridge {{Elements}}: {{Historical Theory}} and {{Practice}}},
publisher = {Cambridge University Press},
location = {Cambridge},
doi = {10.1017/9781009175548},
url = {https://www.cambridge.org/core/elements/collaborative-historical-research-in-the-age-of-big-data/839C422CCAA6C1699DE8D353B3A1960D},
urldate = {2023-01-26},
abstract = {This book is output of the Living with Machines project},
langid = {english},
language = {en},
keywords = {field: History,project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/ET5S8DMH/Ahnert et al. - 2023 - Collaborative Historical Research in the Age of Big Data Lessons from an Interdisciplinary Project.pdf}
}
% == BibLateX quality report for AhnertEtAl2023CollaborativeHistoricalResearch:
% ? Title looks like it was stored in title-case in Zotero
@report{AltenhonerEtAl2023DFGPraxisregeln,
title = {DFG-Praxisregeln "Digitalisierung". Aktualisierte Fassung 2022.},
author = {Altenhöner, Reinhard and Berger, Andreas and Bracht, Christian and Klimpel, Paul and Meyer, Sebastian and Neuburger, Andreas and Stäcker, Thomas and Stein, Regine},
date = {2023-02-16},
url = {https://zenodo.org/record/7435724},
urldate = {2023-03-07},
abstract = {Die DFG-Praxisregeln „Digitalisierung“ stellen eine zentrale Grundlage für DFG-geförderte Projekte im Programm „Digitalisierung und Erschließung“ dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschließung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zugänglichkeit und Anschlussfähigkeit geförderter Projekte und der in diesem Zusammenhang entstehenden Infrastruktur. Das vorliegende Dokument stellt eine aktualisierte Fassung der zuletzt 2016 durch die DFG publizierten Praxisregeln dar. Es wurde in Absprache mit der DFG-Geschäftsstelle durch eine vom NFDI-Konsortium NFDI4Culture initiierte Autor*innengruppe erarbeitet, deren Mitglieder mehrheitlich seit langem an der Ausgestaltung der Praxisregeln beteiligt waren sowie aktiv in die NFDI-Konsortien NFDI4Culture, NFDI4Memory, NFDI4Objects und Text+ eingebunden sind. Die jetzt überarbeitet vorliegenden Praxisregeln „Digitalisierung“ dienen als Ausgangspunkt für eine material- und communitybezogene Ausdifferenzierung der Praxisregeln durch die Communitys. Alle mit der Digitalisierung forschungsrelevanter Objekte befassten Communitys und Einrichtungen sind dazu aufgerufen, mit ihrer Expertise am weiteren Prozess mitzuwirken.},
langid = {deu},
language = {deu},
keywords = {Digital Scholarly Editions,Digitalisierung,Erschließung,Informationsinfrastrukturen,NFDI,Praxisregeln,project: documentation,Project: Methods Lab 🥼,Standardbildung,TEI: Text Encoding Initiative},
file = {/home/drezil/Zotero/storage/46FYRPPH/Altenhöner et al. - 2023 - DFG-Praxisregeln Digitalisierung. Aktualisierte Fassung 2022..pdf}
}
% == BibLateX quality report for AltenhonerEtAl2023DFGPraxisregeln:
% Missing required field 'type'
% Missing required field 'institution'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("Zenodo")
@article{BarkerEtAl2022IntroducingFAIR,
title = {Introducing the {{FAIR Principles}} for Research Software},
author = {Barker, Michelle and Chue Hong, Neil P. and Katz, Daniel S. and Lamprecht, Anna-Lena and Martinez-Ortiz, Carlos and Psomopoulos, Fotis and Harrow, Jennifer and Castro, Leyla Jael and Gruenpeter, Morane and Martinez, Paula Andrea and Honeyman, Tom},
date = {2022-10-14},
journaltitle = {Scientific Data},
shortjournal = {Sci Data},
volume = {9},
number = {1},
pages = {622},
publisher = {Nature Publishing Group},
issn = {2052-4463},
doi = {10.1038/s41597-022-01710-x},
url = {https://www.nature.com/articles/s41597-022-01710-x},
urldate = {2024-09-10},
abstract = {Research software is a fundamental and vital part of research, yet significant challenges to discoverability, productivity, quality, reproducibility, and sustainability exist. Improving the practice of scholarship is a common goal of the open science, open source, and FAIR (Findable, Accessible, Interoperable and Reusable) communities and research software is now being understood as a type of digital object to which FAIR should be applied. This emergence reflects a maturation of the research community to better understand the crucial role of FAIR research software in maximising research value. The FAIR for Research Software (FAIR4RS) Working Group has adapted the FAIR Guiding Principles to create the FAIR Principles for Research Software (FAIR4RS Principles). The contents and context of the FAIR4RS Principles are summarised here to provide the basis for discussion of their adoption. Examples of implementation by organisations are provided to share information on how to maximise the value of research outputs, and to encourage others to amplify the importance and impact of this work.},
langid = {english},
language = {en},
keywords = {Policy,project: documentation,Project: Methods Lab 🥼,Research management,RSE: Research Software Engineering},
file = {/home/drezil/Zotero/storage/VRFPNWKW/VRFPNWKW_Barker et al. - 2022 - Introducing the FAIR Principles for research software.pdf}
}
% == BibLateX quality report for BarkerEtAl2022IntroducingFAIR:
% Unexpected field 'publisher'
% ? unused Library catalog ("www.nature.com")
@book{CremerEtAl2024Projektmanagement,
title = {Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit},
editor = {Cremer, Fabian and Dogunke, Swantje and Neubert, Anna Maria and Wübbena, Thorsten},
date = {2024-04},
publisher = {Bielefeld University Press},
location = {Bielefeld},
doi = {10.14361/9783839469675},
abstract = {Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.},
langid = {ngerman},
language = {de},
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/GYJK3NUY/Cremer et al. - 2024 - Projektmanagement und Digital Humanities Zur klugen Gestaltung der Zusammenarbeit.pdf;/home/drezil/Zotero/storage/XQ6AI49P/Cremer et al. - 2024 - Projektmanagement und Digital Humanities Zur klugen Gestaltung der Zusammenarbeit.pdf}
}
% == BibLateX quality report for CremerEtAl2024Projektmanagement:
% Missing required field 'author'
@article{DiehlEtAl2025JournalOpenSource,
title = {The {{Journal}} of {{Open Source Software}} ({{JOSS}}): {{Bringing Open-Source Software Practices}} to the {{Scholarly Publishing Community}} for {{Authors}}, {{Reviewers}}, {{Editors}}, and {{Publishers}}},
shorttitle = {The {{Journal}} of {{Open Source Software}} ({{JOSS}})},
author = {Diehl, Patrick and Soneson, Charlotte and Kurchin, Rachel C. and Mounce, Ross and Katz, Daniel S.},
date = {2025-02-04},
journaltitle = {Journal of Librarianship and Scholarly Communication},
volume = {12},
number = {2},
publisher = {Iowa State University Digital Press},
issn = {2162-3309},
doi = {10.31274/jlsc.18285},
url = {https://www.iastatedigitalpress.com/jlsc/article/id/18285/},
urldate = {2025-05-15},
abstract = {Introduction: Open-source software (OSS) is a critical component of open science, but contributions to the OSS ecosystem are systematically undervalued in the current academic system. The Journal of Open Source Software (JOSS) contributes to addressing this by providing a venue (that is itself free, diamond open access, and all open-source, built in a layered structure using widely available elements/services of the scholarly publishing ecosystem) for publishing OSS, run in the style of OSS itself. A particularly distinctive element of JOSS is that it uses open peer review in a collaborative, iterative format, unlike most publishers. Additionally, all the components of the process—from the reviews to the papers to the software that is the subject of the papers to the software that the journal runs—are open. Background: We describe JOSS’s history and its peer review process using an editorial bot, and we present statistics gathered from JOSS’s public review history on GitHub showing an increasing number of peer reviewed papers each year. We discuss the new JOSSCast and use it as a data source to understand reasons why interviewed authors decided to publish in JOSS. Discussion and Outlook: JOSS’s process differs significantly from traditional journals, which has impeded JOSS’s inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italy’s, which emphasize the importance of Web of Science and/or Scopus indexing for grant applications and promotions. JOSS is a fully diamond open-access journal with a cost of around US\$5 per paper for the 401 papers published in 2023. The scalability of running JOSS with volunteers and financing JOSS with grants and donations is discussed.},
issue = {2},
langid = {english},
language = {eng},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/G4T6JNUU/Diehl et al. - 2025 - The Journal of Open Source Software (JOSS) Bringing Open-Source Software Practices to the Scholarly.pdf}
}
% == BibLateX quality report for DiehlEtAl2025JournalOpenSource:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.iastatedigitalpress.com")
@misc{EndingsPrinciples221,
title = {Endings {{Principles}} for {{Digital Longevity}}},
shorttitle = {Endings {{Principles}}},
author = {{Endings Project Team}},
date = {2023-03-03},
url = {https://endings.uvic.ca/principles.html},
urldate = {2024-05-14},
abstract = {Enabling Sustainable Digital Humanities Projects},
langid = {english},
language = {en},
version = {2.2.1},
keywords = {project: documentation,Project: Methods Lab 🥼,Project: Tool Registry 🧰,talk: 2024 Bochum,writing: 2024 Tool Registry}
}
% == BibLateX quality report for EndingsPrinciples221:
% ? Title looks like it was stored in title-case in Zotero
@standard{Forschungsgemeinschaft2025LeitlinienzurSicherung,
title = {Leitlinien zur Sicherung guter wissenschaftlicher Praxis},
date = {2024-09},
publisher = {Deutsche Forschungsgemeinschaft},
doi = {10.5281/zenodo.14281892},
url = {https://zenodo.org/records/14281892},
urldate = {2025-05-15},
abstract = {The DFG´s Code of Conduct “Safeguarding Good Research Practice” represents the consensus among the member organisations of the DFG on the fundamental principles and standards of good practice and are upheld by these organisations. These guidelines underline the importance of integrity in the everyday practice of research and provide researchers with a reliable reference with which to embed good research practice as an established and binding aspect of their work.},
langid = {ngerman},
language = {de},
version = {1.2},
keywords = {code of conduct,Deutsche Forschungsgemeinschaft,DFG,German research foundation,good scientific practice,gute wissenschaftliche Praxis,Kodex,Leitlinien zur Sicherung guter wissenschaftlicher Praxis,project: documentation,Project: Methods Lab 🥼,research integrity,scientific misconduct,Wissenschaftliche Integrität,wissenschaftliches Fehlverhalten},
file = {/home/drezil/Zotero/storage/DMF478TJ/2024 - Leitlinien zur Sicherung guter wissenschaftlicher Praxis.pdf}
}
% == BibLateX quality report for Forschungsgemeinschaft2025LeitlinienzurSicherung:
% Unexpected field 'title'
% Unexpected field 'publisher'
% Unexpected field 'language'
% Unexpected field 'version'
% ? unused Committee ("Team „Wissenschaftliche Integrität“")
% ? unused Library catalog ("Zenodo")
@book{Kemman2021Trading,
title = {Trading {{Zones}} of {{Digital History}}},
author = {Kemman, Max},
date = {2021},
series = {Studies in {{Digital History}} and {{Hermeneutics}}},
number = {1},
publisher = {De Gruyter Oldenbourg},
location = {Berlin, Boston},
doi = {10.1515/9783110682106},
url = {https://www.degruyter.com/document/doi/10.1515/9783110682106/html},
urldate = {2021-09-23},
abstract = {Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.},
isbn = {978-3-11-068210-6},
langid = {english},
language = {en},
pagetotal = {182},
keywords = {Digital History,Eintrag bereinigt,PDF (Dropbox),project: documentation,TH-MA-Bloomsbury},
file = {/home/drezil/Zotero/storage/ZS2QA2H6/Kemman - 2021 - Trading Zones of Digital History.pdf}
}
% == BibLateX quality report for Kemman2021Trading:
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.degruyter.com")
@inproceedings{KluyverEtAl2016JupyterNotebookspublishing,
title = {Jupyter {{Notebooks}} – a Publishing Format for Reproducible Computational Workflows},
author = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team},
editor = {Loizides, Fernando and Scmidt, Birgit},
namea = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team and Loizides, Fernando and Scmidt, Birgit},
nameatype = {collaborator},
date = {2016},
pages = {87--90},
publisher = {IOS Press},
doi = {10.3233/978-1-61499-649-1-87},
url = {https://eprints.soton.ac.uk/403913/},
urldate = {2025-05-15},
abstract = {It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.},
eventtitle = {20th {{International Conference}} on {{Electronic Publishing}} (01/01/16)},
langid = {english},
language = {en},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/QB33NJLA/Kluyver et al. - 2016 - Jupyter Notebooks – a publishing format for reproducible computational workflows.pdf}
}
% == BibLateX quality report for KluyverEtAl2016JupyterNotebookspublishing:
% Missing required field 'booktitle'
% ? unused Library catalog ("eprints.soton.ac.uk")
@article{lamprecht2020towards,
title = {Towards {{FAIR}} Principles for~Research~Software},
author = {Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and Dominguez Del Angel, Victoria and family=Sandt, given=Stephanie, prefix=van de, useprefix=true and Ison, Jon and Martinez, Paula Andrea and McQuilton, Peter and Valencia, Alfonso and Harrow, Jennifer and Psomopoulos, Fotis and Gelpi, Josep Ll. and Chue Hong, Neil and Goble, Carole and Capella-Gutierrez, Salvador},
date = {2020-06-12},
journaltitle = {Data Science},
volume = {3},
number = {1},
pages = {37--59},
publisher = {SAGE Publications},
issn = {2451-8484},
doi = {10.3233/DS-190026},
url = {https://doi.org/10.3233/DS-190026},
urldate = {2025-05-15},
abstract = {The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.},
langid = {english},
language = {EN},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/CCXUNESS/Lamprecht et al. - 2020 - Towards FAIR principles for research software.pdf}
}
% == BibLateX quality report for lamprecht2020towards:
% Unexpected field 'publisher'
% ? unused Library catalog ("SAGE Journals")
@article{Lee2018Tensimplerules,
title = {Ten Simple Rules for Documenting Scientific Software},
author = {Lee, Benjamin D.},
date = {2018-12-20},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {14},
number = {12},
pages = {e1006561},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1006561},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561},
urldate = {2025-05-15},
langid = {english},
language = {en},
keywords = {Citation analysis,Computer software,Genome analysis,Genomics,Open source software,project: documentation,Project: Methods Lab 🥼,Software development,Software tools,Source code},
file = {/home/drezil/Zotero/storage/Y72BUDFA/Lee - 2018 - Ten simple rules for documenting scientific software.pdf}
}
% == BibLateX quality report for Lee2018Tensimplerules:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")
@article{NoyEtAl2019IndustryscaleKnowledge,
@article{Smith2016SoftwareCitationPrinciples,
title = {Software Citation Principles},
author = {Smith, Arfon M. and Katz, Daniel S. and Niemeyer, Kyle E.},
date = {2016},
@ -574,35 +293,11 @@
annotation = {Keine weiteren Informationen gefunden},
file = {/home/drezil/Zotero/storage/XVF927LY/Smith et al. - 2016 - Software citation principles.pdf}
}
% == BibLateX quality report for NoyEtAl2019IndustryscaleKnowledge:
% == BibLateX quality report for Smith2016SoftwareCitationPrinciples:
% Unexpected field 'publisher'
% ? unused Library catalog ("peerj.com")
@article{PrlicProcter2012TenSimpleRules,
title = {Ten {{Simple Rules}} for the {{Open Development}} of {{Scientific Software}}},
author = {Prlić, Andreas and Procter, James B.},
date = {2012-12-06},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {8},
number = {12},
pages = {e1002802},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1002802},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802},
urldate = {2025-05-15},
langid = {english},
language = {en},
keywords = {Computer software,Eyes,Open source software,project: documentation,Project: Methods Lab 🥼,Research funding,Scientists,Software tools,Source code,Sustainability science},
file = {/home/drezil/Zotero/storage/STZFWU4P/Prlić and Procter - 2012 - Ten Simple Rules for the Open Development of Scientific Software.pdf}
}
% == BibLateX quality report for PrlicProcter2012TenSimpleRules:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("PLoS Journals")
@article{WilsonEtAl2017Goodenoughpractices,
@article{Wilson2017GoodEnoughPractices,
title = {Good Enough Practices in Scientific Computing},
author = {Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K.},
date = {2017-06-22},
@ -622,310 +317,6 @@
keywords = {Computer software,Control systems,Data management,Metadata,Programming languages,project: documentation,Project: Methods Lab 🥼,Reproducibility,Software tools,Source code},
file = {/home/drezil/Zotero/storage/KWWLZBNY/Wilson et al. - 2017 - Good enough practices in scientific computing.pdf}
}
% == BibLateX quality report for WilsonEtAl2017Goodenoughpractices:
% == BibLateX quality report for Wilson2017GoodEnoughPractices:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")
@book{AhnertEtAl2023CollaborativeHistoricalResearch,
title = {Collaborative {{Historical Research}} in the {{Age}} of {{Big Data}}: {{Lessons}} from an {{Interdisciplinary Project}}},
shorttitle = {Collaborative {{Historical Research}} in the {{Age}} of {{Big Data}}},
author = {Ahnert, Ruth and Griffin, Emma and Ridge, Mia and Tolfo, Giorgia},
date = {2023},
series = {Cambridge {{Elements}}: {{Historical Theory}} and {{Practice}}},
publisher = {Cambridge University Press},
location = {Cambridge},
doi = {10.1017/9781009175548},
url = {https://www.cambridge.org/core/elements/collaborative-historical-research-in-the-age-of-big-data/839C422CCAA6C1699DE8D353B3A1960D},
urldate = {2023-01-26},
abstract = {This book is output of the Living with Machines project},
langid = {english},
language = {en},
keywords = {field: History,project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/ET5S8DMH/Ahnert et al. - 2023 - Collaborative Historical Research in the Age of Big Data Lessons from an Interdisciplinary Project.pdf}
}
% == BibLateX quality report for AhnertEtAl2023CollaborativeHistoricalResearch:
% ? Title looks like it was stored in title-case in Zotero
@report{AltenhonerEtAl2023DFGPraxisregeln,
title = {DFG-Praxisregeln "Digitalisierung". Aktualisierte Fassung 2022.},
author = {Altenhöner, Reinhard and Berger, Andreas and Bracht, Christian and Klimpel, Paul and Meyer, Sebastian and Neuburger, Andreas and Stäcker, Thomas and Stein, Regine},
date = {2023-02-16},
url = {https://zenodo.org/record/7435724},
urldate = {2023-03-07},
abstract = {Die DFG-Praxisregeln „Digitalisierung“ stellen eine zentrale Grundlage für DFG-geförderte Projekte im Programm „Digitalisierung und Erschließung“ dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschließung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zugänglichkeit und Anschlussfähigkeit geförderter Projekte und der in diesem Zusammenhang entstehenden Infrastruktur. Das vorliegende Dokument stellt eine aktualisierte Fassung der zuletzt 2016 durch die DFG publizierten Praxisregeln dar. Es wurde in Absprache mit der DFG-Geschäftsstelle durch eine vom NFDI-Konsortium NFDI4Culture initiierte Autor*innengruppe erarbeitet, deren Mitglieder mehrheitlich seit langem an der Ausgestaltung der Praxisregeln beteiligt waren sowie aktiv in die NFDI-Konsortien NFDI4Culture, NFDI4Memory, NFDI4Objects und Text+ eingebunden sind. Die jetzt überarbeitet vorliegenden Praxisregeln „Digitalisierung“ dienen als Ausgangspunkt für eine material- und communitybezogene Ausdifferenzierung der Praxisregeln durch die Communitys. Alle mit der Digitalisierung forschungsrelevanter Objekte befassten Communitys und Einrichtungen sind dazu aufgerufen, mit ihrer Expertise am weiteren Prozess mitzuwirken.},
langid = {deu},
language = {deu},
keywords = {Digital Scholarly Editions,Digitalisierung,Erschließung,Informationsinfrastrukturen,NFDI,Praxisregeln,project: documentation,Project: Methods Lab 🥼,Standardbildung,TEI: Text Encoding Initiative},
file = {/home/drezil/Zotero/storage/46FYRPPH/Altenhöner et al. - 2023 - DFG-Praxisregeln Digitalisierung. Aktualisierte Fassung 2022..pdf}
}
% == BibLateX quality report for AltenhonerEtAl2023DFGPraxisregeln:
% Missing required field 'type'
% Missing required field 'institution'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("Zenodo")
@article{BarkerEtAl2022IntroducingFAIR,
title = {Introducing the {{FAIR Principles}} for Research Software},
author = {Barker, Michelle and Chue Hong, Neil P. and Katz, Daniel S. and Lamprecht, Anna-Lena and Martinez-Ortiz, Carlos and Psomopoulos, Fotis and Harrow, Jennifer and Castro, Leyla Jael and Gruenpeter, Morane and Martinez, Paula Andrea and Honeyman, Tom},
date = {2022-10-14},
journaltitle = {Scientific Data},
shortjournal = {Sci Data},
volume = {9},
number = {1},
pages = {622},
publisher = {Nature Publishing Group},
issn = {2052-4463},
doi = {10.1038/s41597-022-01710-x},
url = {https://www.nature.com/articles/s41597-022-01710-x},
urldate = {2024-09-10},
abstract = {Research software is a fundamental and vital part of research, yet significant challenges to discoverability, productivity, quality, reproducibility, and sustainability exist. Improving the practice of scholarship is a common goal of the open science, open source, and FAIR (Findable, Accessible, Interoperable and Reusable) communities and research software is now being understood as a type of digital object to which FAIR should be applied. This emergence reflects a maturation of the research community to better understand the crucial role of FAIR research software in maximising research value. The FAIR for Research Software (FAIR4RS) Working Group has adapted the FAIR Guiding Principles to create the FAIR Principles for Research Software (FAIR4RS Principles). The contents and context of the FAIR4RS Principles are summarised here to provide the basis for discussion of their adoption. Examples of implementation by organisations are provided to share information on how to maximise the value of research outputs, and to encourage others to amplify the importance and impact of this work.},
langid = {english},
language = {en},
keywords = {Policy,project: documentation,Project: Methods Lab 🥼,Research management,RSE: Research Software Engineering},
file = {/home/drezil/Zotero/storage/VRFPNWKW/VRFPNWKW_Barker et al. - 2022 - Introducing the FAIR Principles for research software.pdf}
}
% == BibLateX quality report for BarkerEtAl2022IntroducingFAIR:
% Unexpected field 'publisher'
% ? unused Library catalog ("www.nature.com")
@book{CremerEtAl2024Projektmanagement,
title = {Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit},
editor = {Cremer, Fabian and Dogunke, Swantje and Neubert, Anna Maria and Wübbena, Thorsten},
date = {2024-04},
publisher = {Bielefeld University Press},
location = {Bielefeld},
doi = {10.14361/9783839469675},
abstract = {Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.},
langid = {ngerman},
language = {de},
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/GYJK3NUY/Cremer et al. - 2024 - Projektmanagement und Digital Humanities Zur klugen Gestaltung der Zusammenarbeit.pdf;/home/drezil/Zotero/storage/XQ6AI49P/Cremer et al. - 2024 - Projektmanagement und Digital Humanities Zur klugen Gestaltung der Zusammenarbeit.pdf}
}
% == BibLateX quality report for CremerEtAl2024Projektmanagement:
% Missing required field 'author'
@article{DiehlEtAl2025JournalOpenSource,
title = {The {{Journal}} of {{Open Source Software}} ({{JOSS}}): {{Bringing Open-Source Software Practices}} to the {{Scholarly Publishing Community}} for {{Authors}}, {{Reviewers}}, {{Editors}}, and {{Publishers}}},
shorttitle = {The {{Journal}} of {{Open Source Software}} ({{JOSS}})},
author = {Diehl, Patrick and Soneson, Charlotte and Kurchin, Rachel C. and Mounce, Ross and Katz, Daniel S.},
date = {2025-02-04},
journaltitle = {Journal of Librarianship and Scholarly Communication},
volume = {12},
number = {2},
publisher = {Iowa State University Digital Press},
issn = {2162-3309},
doi = {10.31274/jlsc.18285},
url = {https://www.iastatedigitalpress.com/jlsc/article/id/18285/},
urldate = {2025-05-15},
abstract = {Introduction: Open-source software (OSS) is a critical component of open science, but contributions to the OSS ecosystem are systematically undervalued in the current academic system. The Journal of Open Source Software (JOSS) contributes to addressing this by providing a venue (that is itself free, diamond open access, and all open-source, built in a layered structure using widely available elements/services of the scholarly publishing ecosystem) for publishing OSS, run in the style of OSS itself. A particularly distinctive element of JOSS is that it uses open peer review in a collaborative, iterative format, unlike most publishers. Additionally, all the components of the process—from the reviews to the papers to the software that is the subject of the papers to the software that the journal runs—are open. Background: We describe JOSS’s history and its peer review process using an editorial bot, and we present statistics gathered from JOSS’s public review history on GitHub showing an increasing number of peer reviewed papers each year. We discuss the new JOSSCast and use it as a data source to understand reasons why interviewed authors decided to publish in JOSS. Discussion and Outlook: JOSS’s process differs significantly from traditional journals, which has impeded JOSS’s inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italy’s, which emphasize the importance of Web of Science and/or Scopus indexing for grant applications and promotions. JOSS is a fully diamond open-access journal with a cost of around US\$5 per paper for the 401 papers published in 2023. The scalability of running JOSS with volunteers and financing JOSS with grants and donations is discussed.},
issue = {2},
langid = {english},
language = {eng},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/G4T6JNUU/Diehl et al. - 2025 - The Journal of Open Source Software (JOSS) Bringing Open-Source Software Practices to the Scholarly.pdf}
}
% == BibLateX quality report for DiehlEtAl2025JournalOpenSource:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.iastatedigitalpress.com")
@misc{EndingsPrinciples221,
title = {Endings {{Principles}} for {{Digital Longevity}}},
shorttitle = {Endings {{Principles}}},
author = {{Endings Project Team}},
date = {2023-03-03},
url = {https://endings.uvic.ca/principles.html},
urldate = {2024-05-14},
abstract = {Enabling Sustainable Digital Humanities Projects},
langid = {english},
language = {en},
version = {2.2.1},
keywords = {project: documentation,Project: Methods Lab 🥼,Project: Tool Registry 🧰,talk: 2024 Bochum,writing: 2024 Tool Registry}
}
% == BibLateX quality report for EndingsPrinciples221:
% ? Title looks like it was stored in title-case in Zotero
@standard{Forschungsgemeinschaft2025LeitlinienzurSicherung,
title = {Leitlinien zur Sicherung guter wissenschaftlicher Praxis},
date = {2024-09},
publisher = {Deutsche Forschungsgemeinschaft},
doi = {10.5281/zenodo.14281892},
url = {https://zenodo.org/records/14281892},
urldate = {2025-05-15},
abstract = {The DFG´s Code of Conduct “Safeguarding Good Research Practice” represents the consensus among the member organisations of the DFG on the fundamental principles and standards of good practice and are upheld by these organisations. These guidelines underline the importance of integrity in the everyday practice of research and provide researchers with a reliable reference with which to embed good research practice as an established and binding aspect of their work.},
langid = {ngerman},
language = {de},
version = {1.2},
keywords = {code of conduct,Deutsche Forschungsgemeinschaft,DFG,German research foundation,good scientific practice,gute wissenschaftliche Praxis,Kodex,Leitlinien zur Sicherung guter wissenschaftlicher Praxis,project: documentation,Project: Methods Lab 🥼,research integrity,scientific misconduct,Wissenschaftliche Integrität,wissenschaftliches Fehlverhalten},
file = {/home/drezil/Zotero/storage/DMF478TJ/2024 - Leitlinien zur Sicherung guter wissenschaftlicher Praxis.pdf}
}
% == BibLateX quality report for Forschungsgemeinschaft2025LeitlinienzurSicherung:
% Unexpected field 'title'
% Unexpected field 'publisher'
% Unexpected field 'language'
% Unexpected field 'version'
% ? unused Committee ("Team „Wissenschaftliche Integrität“")
% ? unused Library catalog ("Zenodo")
@book{Kemman2021Trading,
title = {Trading {{Zones}} of {{Digital History}}},
author = {Kemman, Max},
date = {2021},
series = {Studies in {{Digital History}} and {{Hermeneutics}}},
number = {1},
publisher = {De Gruyter Oldenbourg},
location = {Berlin, Boston},
doi = {10.1515/9783110682106},
url = {https://www.degruyter.com/document/doi/10.1515/9783110682106/html},
urldate = {2021-09-23},
abstract = {Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.},
isbn = {978-3-11-068210-6},
langid = {english},
language = {en},
pagetotal = {182},
keywords = {Digital History,Eintrag bereinigt,PDF (Dropbox),project: documentation,TH-MA-Bloomsbury},
file = {/home/drezil/Zotero/storage/ZS2QA2H6/Kemman - 2021 - Trading Zones of Digital History.pdf}
}
% == BibLateX quality report for Kemman2021Trading:
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.degruyter.com")
@inproceedings{KluyverEtAl2016JupyterNotebookspublishing,
title = {Jupyter {{Notebooks}} – a Publishing Format for Reproducible Computational Workflows},
author = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team},
editor = {Loizides, Fernando and Scmidt, Birgit},
namea = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team and Loizides, Fernando and Scmidt, Birgit},
nameatype = {collaborator},
date = {2016},
pages = {87--90},
publisher = {IOS Press},
doi = {10.3233/978-1-61499-649-1-87},
url = {https://eprints.soton.ac.uk/403913/},
urldate = {2025-05-15},
abstract = {It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.},
eventtitle = {20th {{International Conference}} on {{Electronic Publishing}} (01/01/16)},
langid = {english},
language = {en},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/QB33NJLA/Kluyver et al. - 2016 - Jupyter Notebooks – a publishing format for reproducible computational workflows.pdf}
}
% == BibLateX quality report for KluyverEtAl2016JupyterNotebookspublishing:
% Missing required field 'booktitle'
% ? unused Library catalog ("eprints.soton.ac.uk")
@article{lamprecht2020towards,
title = {Towards {{FAIR}} Principles for~Research~Software},
author = {Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and Dominguez Del Angel, Victoria and family=Sandt, given=Stephanie, prefix=van de, useprefix=true and Ison, Jon and Martinez, Paula Andrea and McQuilton, Peter and Valencia, Alfonso and Harrow, Jennifer and Psomopoulos, Fotis and Gelpi, Josep Ll. and Chue Hong, Neil and Goble, Carole and Capella-Gutierrez, Salvador},
date = {2020-06-12},
journaltitle = {Data Science},
volume = {3},
number = {1},
pages = {37--59},
publisher = {SAGE Publications},
issn = {2451-8484},
doi = {10.3233/DS-190026},
url = {https://doi.org/10.3233/DS-190026},
urldate = {2025-05-15},
abstract = {The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.},
langid = {english},
language = {EN},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/CCXUNESS/Lamprecht et al. - 2020 - Towards FAIR principles for research software.pdf}
}
% == BibLateX quality report for lamprecht2020towards:
% Unexpected field 'publisher'
% ? unused Library catalog ("SAGE Journals")
@article{Lee2018Tensimplerules,
title = {Ten Simple Rules for Documenting Scientific Software},
author = {Lee, Benjamin D.},
date = {2018-12-20},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {14},
number = {12},
pages = {e1006561},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1006561},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561},
urldate = {2025-05-15},
langid = {english},
language = {en},
keywords = {Citation analysis,Computer software,Genome analysis,Genomics,Open source software,project: documentation,Project: Methods Lab 🥼,Software development,Software tools,Source code},
file = {/home/drezil/Zotero/storage/Y72BUDFA/Lee - 2018 - Ten simple rules for documenting scientific software.pdf}
}
% == BibLateX quality report for Lee2018Tensimplerules:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")
@article{NoyEtAl2019IndustryscaleKnowledge,
title = {Software Citation Principles},
author = {Smith, Arfon M. and Katz, Daniel S. and Niemeyer, Kyle E.},
date = {2016},
journaltitle = {PeerJ Computer Science},
shortjournal = {PeerJ Comput. Sci.},
volume = {2},
publisher = {PeerJ Inc.},
issn = {2376-5992},
doi = {10.7717/peerj-cs.86},
url = {https://peerj.com/articles/cs-86},
urldate = {2020-09-11},
abstract = {Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.},
langid = {english},
language = {en},
keywords = {Eintrag bereinigt,PDF (Dropbox),project: documentation,Project: Methods Lab 🥼,Research Software Engineering},
annotation = {Keine weiteren Informationen gefunden},
file = {/home/drezil/Zotero/storage/XVF927LY/Smith et al. - 2016 - Software citation principles.pdf}
}
% == BibLateX quality report for NoyEtAl2019IndustryscaleKnowledge:
% Unexpected field 'publisher'
% ? unused Library catalog ("peerj.com")
@article{PrlicProcter2012TenSimpleRules,
title = {Ten {{Simple Rules}} for the {{Open Development}} of {{Scientific Software}}},
author = {Prlić, Andreas and Procter, James B.},
date = {2012-12-06},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {8},
number = {12},
pages = {e1002802},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1002802},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802},
urldate = {2025-05-15},
langid = {english},
language = {en},
keywords = {Computer software,Eyes,Open source software,project: documentation,Project: Methods Lab 🥼,Research funding,Scientists,Software tools,Source code,Sustainability science},
file = {/home/drezil/Zotero/storage/STZFWU4P/Prlić and Procter - 2012 - Ten Simple Rules for the Open Development of Scientific Software.pdf}
}
% == BibLateX quality report for PrlicProcter2012TenSimpleRules:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("PLoS Journals")
@article{WilsonEtAl2017Goodenoughpractices,
title = {Good Enough Practices in Scientific Computing},
author = {Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K.},
date = {2017-06-22},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {13},
number = {6},
pages = {e1005510},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1005510},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510},
urldate = {2025-05-15},
abstract = {Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don't know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.},
langid = {english},
language = {en},
keywords = {Computer software,Control systems,Data management,Metadata,Programming languages,project: documentation,Project: Methods Lab 🥼,Reproducibility,Software tools,Source code},
file = {/home/drezil/Zotero/storage/KWWLZBNY/Wilson et al. - 2017 - Good enough practices in scientific computing.pdf}
}
% == BibLateX quality report for WilsonEtAl2017Goodenoughpractices:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")