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

added first try of references for websites & software

Browse Source
This commit is contained in:
Nicole Dresselhaus 2025-06-03 11:21:35 +02:00
parent c72a3f255c
commit 8dd32b411b
3 changed files with 452 additions and 303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
background/BACKGROUND.html
View File

@ -2166,13 +2166,20 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<meta name="citation_year" content="2025">
<meta name="citation_online_date" content="2025-05-08">
<meta name="citation_language" content="de">
<meta name="citation_reference" content="citation_title=Good enough practices in scientific computing;,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;,citation_cover_date=2017;,citation_year=2017;,citation_issue=6;,citation_volume=13;,citation_journal_title=PLoS computational biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Ten simple rules for documenting scientific software;,citation_author=Andreas Prlić;,citation_author=James B Procter;,citation_publication_date=2012;,citation_cover_date=2012;,citation_year=2012;,citation_issue=12;,citation_volume=8;,citation_journal_title=PLoS Computational Biology;,citation_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Software citation principles;,citation_author=Arfon M Smith;,citation_author=Daniel S Katz;,citation_author=Kyle E Niemeyer;,citation_author=FORCE11 Software Citation Working Group;,citation_author=others;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_volume=2;,citation_journal_title=PeerJ Computer Science;,citation_publisher=PeerJ Inc.;">
<meta name="citation_reference" content="citation_title=Jupyter notebooks—a publishing format for reproducible computational workflows;,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 B Hamrick;,citation_author=Jason Grout;,citation_author=Sylvain Corlay;,citation_author=others;,citation_publication_date=2016;,citation_cover_date=2016;,citation_year=2016;,citation_volume=20;,citation_journal_title=Positioning and Power in Academic Publishing: Players, Agents and Agendas;,citation_publisher=IOS Press;">
<meta name="citation_reference" content="citation_title=Endings Principles for Digital Longevity;,citation_author=Endings Project;,citation_publication_date=2020;,citation_cover_date=2020;,citation_year=2020;,citation_fulltext_html_url=https://endings.uvic.ca/principles.html;">
<meta name="citation_reference" content="citation_title=The Journal of Open Source Software (JOSS);,citation_author=Daniel S Katz;,citation_author=Kyle E Niemeyer;,citation_author=Arfon M Smith;,citation_publication_date=2021;,citation_cover_date=2021;,citation_year=2021;,citation_volume=7;,citation_journal_title=PeerJ Computer Science;,citation_publisher=PeerJ Inc.;">
<meta name="citation_reference" content="citation_title=Towards 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=others;,citation_publication_date=2020;,citation_cover_date=2020;,citation_year=2020;,citation_issue=1;,citation_volume=3;,citation_journal_title=Data Science;,citation_publisher=IOS Press;">
<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_publisher=PeerJ Inc.;">
<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_book_title=Trading Zones of Digital History;,citation_series_title=Studies in Digital History and Hermeneutics;">
<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;,citation_cover_date=2022-10;,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_publisher=Nature Publishing Group;">
<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;,citation_cover_date=2017-06;,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_publisher=Public Library of Science;">
<meta name="citation_reference" content="citation_title=Ten Simple Rules for Documenting Scientific Software;,citation_author=Benjamin D. Lee;,citation_publication_date=2018-12;,citation_cover_date=2018-12;,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_publisher=Public Library of Science;">
<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 development 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_title=20th International Conference on Electronic Publishing (01/01/16);,citation_conference=IOS 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;,citation_cover_date=2023-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=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;,citation_cover_date=2020-06;,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=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;,citation_cover_date=2025-02;,citation_year=2025;,citation_fulltext_html_url=https://www.iastatedigitalpress.com/jlsc/article/id/18285/;,citation_issue=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=Ten Simple Rules for the Open Development of Scientific Software;,citation_author=Andreas Prlić;,citation_author=James B. Procter;,citation_publication_date=2012-12;,citation_cover_date=2012-12;,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_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=Leitlinien zur Sicherung guter wissenschaftlicher Praxis;,citation_abstract=The DFGs 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=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;,citation_cover_date=2023-02;,citation_year=2023;,citation_fulltext_html_url=https://zenodo.org/record/7435724;,citation_language=deu;">
</head>
<body class="quarto-light">
@ -2229,6 +2236,9 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<li><a href="#tabellarische-übersicht-der-dokumentations-bestandteile" id="toc-tabellarische-übersicht-der-dokumentations-bestandteile" class="nav-link" data-scroll-target="#tabellarische-übersicht-der-dokumentations-bestandteile">Tabellarische Übersicht der Dokumentations-Bestandteile</a></li>
<li><a href="#schlusswort" id="toc-schlusswort" class="nav-link" data-scroll-target="#schlusswort">Schlusswort</a></li>
</ul></li>
</ul>
</nav>
</div>
@ -2300,8 +2310,8 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<section id="einleitung" class="level2 page-columns page-full">
<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>
<div class="page-columns page-full"><p></p><div class="no-row-height column-margin column-container"><span class="margin-aside">Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien <span class="citation" data-cites="prlic2012ten wilson2017good katz2021open endings2020principles">[<a href="#ref-prlic2012ten" role="doc-biblioref">1</a>–<a href="#ref-endings2020principles" role="doc-biblioref">4</a>]</span>.</span></div></div>
<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 insbesondere die Prinzipien des <em>Endings-Projekts</em> für digitale Langlebigkeit <span class="citation" data-cites="endings2020principles">[<a href="#ref-endings2020principles" role="doc-biblioref">4</a>]</span>. 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. 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>
<div class="page-columns page-full"><p></p><div class="no-row-height column-margin column-container"><span class="margin-aside">Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien <span class="citation" data-cites="PrlicProcter2012TenSimpleRules WilsonEtAl2017Goodenoughpractices BarkerEtAl2022IntroducingFAIR EndingsPrinciples221">[<a href="#ref-PrlicProcter2012TenSimpleRules" role="doc-biblioref">1</a>–<a href="#ref-EndingsPrinciples221" role="doc-biblioref">4</a>]</span>.</span></div></div>
<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 insbesondere die Prinzipien des <em>Endings-Projekts</em> für digitale Langlebigkeit <span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">4</a>]</span>. 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. 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>
@ -2312,7 +2322,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
</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>
<div class="page-columns page-full"><p>Dokumentieren Sie alle <em>Eingabeformate, Ausgabedaten und verwendeten Datensätze</em>. Nutzer*innen müssen wissen, welche Daten die Software erwartet (Dateiformate, Schnittstellen, Parameter) und welche Ergebnisse sie produziert. Idealerweise werden Beispiele angegeben: z. B. Beispiel-Dateien oder -Parameter und die korrespondierende Ausgabe. Falls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies umfasst die <strong>Datenmodelle</strong> (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten. Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur in einem <em>statischen Dokument</em> festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert. Eine Tabelle oder Auflistung der Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht die Klarheit. </p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Eingabedatei: CSV mit Spalten <code>Autor</code>, <code>Empfänger</code>, …; Ausgabe: JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”</em></span></div></div>
<div class="page-columns page-full"><p>Dokumentieren Sie alle <em>Eingabeformate, Ausgabedaten und verwendeten Datensätze</em>. Nutzer*innen müssen wissen, welche Daten die Software erwartet (Dateiformate, Schnittstellen, Parameter) und welche Ergebnisse sie produziert. Idealerweise werden Beispiele angegeben: z. B. Beispiel-Dateien oder -Parameter und die korrespondierende Ausgabe. Falls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies umfasst die <strong>Datenmodelle</strong> (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten. Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur in einem <em>statischen Dokument</em> festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert <span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">4</a>]</span>. Eine Tabelle oder Auflistung der Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht die Klarheit. </p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Eingabedatei: CSV mit Spalten <code>Autor</code>, <code>Empfänger</code>, …; Ausgabe: JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”</em></span></div></div>
</section>
<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>
@ -2335,7 +2345,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
</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. <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. 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 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<span class="citation" data-cites="smith2016software">[<a href="#ref-smith2016software" role="doc-biblioref">5</a>]</span>. 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. Diese Praxis entspricht auch den ENDINGS-Prinzipien, die verlangen, dass jede veröffentlichte Version eindeutig erkennbar ist und zitiert werden kann.</p>
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten. <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. 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 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 <span class="citation" data-cites="SmithEtAl2016Softwarecitation">[<a href="#ref-SmithEtAl2016Softwarecitation" role="doc-biblioref">5</a>]</span>. 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. Diese Praxis entspricht auch den ENDINGS-Prinzipien, die verlangen, dass jede veröffentlichte Version eindeutig erkennbar ist und zitiert werden kann.</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>
@ -2347,7 +2357,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<p>Für Forschende ohne viel Ressourcen muss die Dokumentation <strong>einfach zugänglich, leicht pflegbar und ohne Spezialsoftware</strong> erstellbar sein. Daher empfiehlt es sich, auf <strong>leichte Formate</strong> und eine klare Struktur zu setzen:</p>
<section id="readme.md-als-zentrales-dokument" class="level3">
<h3 class="anchored" data-anchor-id="readme.md-als-zentrales-dokument"><code>README.md</code> als zentrales Dokument</h3>
<p>Die Hauptdokumentation sollte als README in Markdown-Format im Hauptverzeichnis des Code-Repositoriums liegen. Dieses README fungiert als “Startseite” des Projekts und enthält idealerweise eine komprimierte Übersicht aller wichtigen Punkte: Zweck der Software, Kurzbeschreibung, Installation, kurzer Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie GitHub, GitLab etc. wird die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die Vorteile von <strong>Markdown</strong> sind die einfache Lesbarkeit in Rohform, die breite Unterstützung (auch in Renderern wie GitHub-Webansicht) und die Eignung für Versionierung (Textdatei im Git). So bleibt die Dokumentation eng mit dem Code verzahnt und unter Versionskontrolle – ein Prinzip, das auch von ENDINGS propagiert wird (Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden).</p>
<p>Die Hauptdokumentation sollte als README in Markdown-Format im Hauptverzeichnis des Code-Repositoriums liegen. Dieses README fungiert als “Startseite” des Projekts und enthält idealerweise eine komprimierte Übersicht aller wichtigen Punkte: Zweck der Software, Kurzbeschreibung, Installation, kurzer Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie <a href="https://github.com" title="Seite mit sehr vielen Open-Source-Projekten, die git verwenden. Gehört zu Microsoft">GitHub</a>, <a href="https://gitlab.com" title="Open-Source-Lösung für selbst gehostete Projektverwaltung (git, issue-tracking, …). Community (kostenfrei; limitierte features) oder Enterprise-Linzenz">GitLab</a> etc. wird die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die Vorteile von <strong><a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a></strong> sind die einfache Lesbarkeit in Rohform, die breite Unterstützung (auch in Renderern wie GitHub-Webansicht) und die Eignung für Versionierung (Textdatei im <a href="https://git-scm.com" title="Versionskontrollsystem">git</a>). So bleibt die Dokumentation eng mit dem Code verzahnt und unter Versionskontrolle – ein Prinzip, das auch von ENDINGS<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">4</a>]</span> propagiert wird (Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden).</p>
</section>
<section id="strukturierte-unterteilung-in-weitere-dateienabschnitte" class="level3 page-columns page-full">
<h3 class="anchored" data-anchor-id="strukturierte-unterteilung-in-weitere-dateienabschnitte">Strukturierte Unterteilung in weitere Dateien/Abschnitte</h3>
@ -2371,7 +2381,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
└── module/
└── helper.py</code></pre>
<p>Beispielhafter Struktur eines Code-Repositories</p>
</div></div><p>Sollte die Dokumentation umfangreicher sein, ist es sinnvoll, sie in logisch getrennte Abschnitte aufzuteilen. Dies kann innerhalb der README durch Überschriften geschehen oder durch <strong>zusätzliche Markdown-Dateien</strong> im Repository (z. B. eine <code>INSTALL.md</code> für ausführliche Installationshinweise, eine <code>USAGE.md</code> oder <code>TUTORIAL.md</code> für detaillierte Benutzeranleitungen, eine <code>CHANGELOG.md</code> für Changelog etc.). Eine gängige Struktur ist z. B.:</p>
</div></div><p>Sollte die Dokumentation umfangreicher sein, ist es sinnvoll, sie in logisch getrennte Abschnitte aufzuteilen. Dies kann innerhalb der README durch Überschriften geschehen oder durch <strong>zusätzliche <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>-Dateien</strong> im Repository (z. B. eine <code>INSTALL.md</code> für ausführliche Installationshinweise, eine <code>USAGE.md</code> oder <code>TUTORIAL.md</code> für detaillierte Benutzeranleitungen, eine <code>CHANGELOG.md</code> für Changelog etc.). Eine gängige Struktur ist z. B.:</p>
<ul>
<li><code>README.md</code> – Überblick (Ziel, Installation, kurzes Beispiel, Lizenz/Zitation)</li>
<li><code>docs/</code> Verzeichnis mit weiteren .md-Dateien für tiefergehende Dokumentation (optional)</li>
@ -2379,23 +2389,34 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
<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 benannt sein, damit sie leicht auffindbar sind. Sie kommen ohne spezielle Tools aus – ein einfacher Texteditor genügt zum Bearbeiten. Auch <strong>Wiki-Seiten</strong> (etwa in GitHub) können genutzt werden, sind aber weniger dauerhaft versioniert im Vergleich zu Dateien im Code-Repository selbst. Die Dokumentation sollte möglichst <em>im Repository</em> selbst liegen, um sicherzustellen, dass sie gemeinsam mit dem Code versioniert, verteilt und archiviert wird. Externe Dokumentationswebsites sind für kleine Projekte oft Overkill und können im schlimmsten Fall verwaisen.</p>
<p>Diese Dateien sollten konsistent formatiert und benannt sein, damit sie leicht auffindbar sind. Sie kommen ohne spezielle Tools aus – ein einfacher Texteditor genügt zum Bearbeiten. Auch <strong>Wiki-Seiten</strong> (etwa in <a href="https://github.com" title="Seite mit sehr vielen Open-Source-Projekten, die git verwenden. Gehört zu Microsoft">GitHub</a>) können genutzt werden, sind aber weniger dauerhaft versioniert im Vergleich zu Dateien im Code-Repository selbst. Die Dokumentation sollte möglichst <em>im Repository</em> selbst liegen, um sicherzustellen, dass sie gemeinsam mit dem Code versioniert, verteilt und archiviert wird. Externe Dokumentationswebsites sind für kleine Projekte oft Overkill und können im schlimmsten Fall verwaisen.</p>
</section>
<section id="keine-proprietären-formate-oder-abhängigkeit-von-werkzeugen" class="level3">
<h3 class="anchored" data-anchor-id="keine-proprietären-formate-oder-abhängigkeit-von-werkzeugen">Keine proprietären Formate oder Abhängigkeit von Werkzeugen</h3>
<p>Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown, reStructuredText). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil des Versionskontrollsystems. Ein Markdown-Dokument hingegen kann gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Zudem erlauben offene Formate eine leichtere <strong>Langzeitarchivierung</strong>: Gemäß Endings-Prinzip sollten Informationsressourcen in langfristig lesbaren Formaten vorliegen. Markdown/Plaintext erfüllt diese Bedingung (im Gegensatz etwa zu einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 Jahren evtl. nicht mehr läuft). Im Sinne der <em>Digital Longevity</em> ist eine <strong>statische HTML- oder PDF-Version</strong> der Dokumentation (automatisch generiert aus Markdown) als Teil der Release-Artefakte sinnvoll – so kann z. B. in jeder veröffentlichten Version ein PDF-Handbuch beigelegt werden, das später zitiert oder referenziert werden kann. <strong>Wichtig ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku bleibt.</strong></p>
<p>Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, sollte auf gängige, offene Formate gesetzt werden (Plaintext, <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>, <a href="https://en.wikipedia.org/wiki/ReStructuredText" title="Alternative zu Markdown.">reStructuredText</a>). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil des Versionskontrollsystems. Ein <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>-Dokument hingegen kann gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Markdown/Plaintext erfüllt die Bedingung der offenen <strong>Langzeitarchivierung</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">4</a>]</span> (im Gegensatz etwa zu einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 Jahren evtl. nicht mehr läuft). Im Sinne der <em>Digital Longevity</em> ist eine <strong>statische HTML- oder PDF-Version</strong> der Dokumentation (automatisch generiert aus <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> via <a href="https://pandoc.org/MANUAL.html#pandocs-markdown" title="DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln und hieraus HTML/PDF u.ä. erstellen">pandoc</a>) als Teil der Release-Artefakte sinnvoll. <strong>Wichtig ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku bleibt.</strong></p>
</section>
<section id="übersichtlichkeit-und-navigierbarkeit" class="level3">
<h3 class="anchored" data-anchor-id="übersichtlichkeit-und-navigierbarkeit">Übersichtlichkeit und Navigierbarkeit</h3>
<p>Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit Leser schnell die gesuchten Informationen finden. Eine <strong>logische Gliederung</strong> (wie in diesem Katalog: Einführung, Anforderungen, Installation, Nutzung, Hintergrund, etc.) hilft unterschiedlichen Nutzergruppen gezielt das Relevante zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine Abschnittsübersicht am Anfang nützlich sein. Markdown bietet z. B. automatische Toc-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an einem Ort). Wiederholungen sollten vermieden werden: lieber an einer Stelle ausführlich dokumentieren und sonst darauf verweisen, um Konsistenzprobleme zu vermeiden (<em>“Don’t Repeat Yourself”</em> gilt auch für Dokumentation). Bei ähnlichen Projekten können Sie sich an bestehenden <strong>Dokumentationsvorlagen</strong> orientieren: Viele erfolgreiche Open-Source-Projekte haben auf GitHub eine ähnliche README-Struktur, die als informelles Template dienen kann.</p>
<p>Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit Leser schnell die gesuchten Informationen finden. Eine <strong>logische Gliederung</strong> hilft unterschiedlichen Nutzergruppen gezielt das Relevante zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine Abschnittsübersicht am Anfang nützlich sein. <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> bietet z. B. automatische TOC-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an einem Ort) und Wiederholungen zu vermeiden. Das Mantra <em>“Don’t Repeat Yourself”</em> gilt auch für Dokumentation.</p>
</section>
<section id="beispiele-codeblöcke-und-ggf.-abbildungen-einbinden" class="level3">
<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 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 (etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche, etc.). 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 (zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder Graphviz). 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>
<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.). 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 (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>). 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>
</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: <strong>Die Dokumentation sollte im gleichen Repository leben wie der Code, klar strukturiert und in einem einfach handhabbaren Format vorliegen.</strong> Sie soll ohne spezielle Umgebung lesbar sein – ein Nutzer, der das Repository klont oder herunterlädt, muss sofort Zugang zur Dokumentation haben. Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software (und deren Doku) <em>auffindbar</em> und <em>zugänglich</em> zu machen, ohne Hürden. Eine gut gepflegte README in Markdown erfüllt diese Anforderungen in den meisten Fällen optimal.</p>
<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>
<p>Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software (und deren Doku) <em>auffindbar</em> und <em>zugänglich</em> zu machen, ohne Hürden. Eine <strong>gut gepflegte</strong> README in <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> erfüllt diese Anforderungen in den meisten Fällen optimal.</p>
<!--
Markierung für mich -.-
-->
</section>
</section>
<section id="umfang-und-fokus-der-dokumentation" class="level2">
@ -2421,7 +2442,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
</section>
<section id="jupyter-notebooks-und-literate-programming" class="level3">
<h3 class="anchored" data-anchor-id="jupyter-notebooks-und-literate-programming">Jupyter Notebooks und literate programming</h3>
<p>Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind <strong>Jupyter Notebooks</strong> bzw. R Markdown Notebooks <span class="citation" data-cites="maria2019jupyter">[<a href="#ref-maria2019jupyter" role="doc-biblioref">6</a>]</span>. Diese erlauben es, <em>ausführbaren Code mit erklärendem Text und Visualisierungen</em> in einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei leisten: (1) als <strong>Tutorials/Beispiel-Workflows</strong>, die Nutzer interaktiv nachvollziehen können, und (2) als <strong>Reproduzierbarkeits-Dokumentation</strong> für analytische Prozesse. Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist, könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der Ergebnisse).</p>
<p>Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind <strong>Jupyter Notebooks</strong> bzw. R Markdown Notebooks <span class="citation" data-cites="KluyverEtAl2016JupyterNotebookspublishing">[<a href="#ref-KluyverEtAl2016JupyterNotebookspublishing" role="doc-biblioref">6</a>]</span>. Diese erlauben es, <em>ausführbaren Code mit erklärendem Text und Visualisierungen</em> in einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei leisten: (1) als <strong>Tutorials/Beispiel-Workflows</strong>, die Nutzer interaktiv nachvollziehen können, und (2) als <strong>Reproduzierbarkeits-Dokumentation</strong> für analytische Prozesse. Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist, könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der Ergebnisse).</p>
<p>Notebooks senken die Hürde, weil Nutzer direkt experimentieren können, und fördern transparente Forschung, da Code, Ergebnisse und Beschreibung zusammenfließen. Sie sind daher sinnvoll, <strong>wenn der Hauptanwendungsfall die Durchführung von Analysen oder Datenverarbeitungen ist</strong>, die man Schritt für Schritt demonstrieren kann.</p>
<div class="callout callout-style-default callout-warning callout-titled">
<div class="callout-header d-flex align-content-center">
@ -2587,28 +2608,49 @@ Warnung
<section id="schlusswort" class="level3">
<h3 class="anchored" data-anchor-id="schlusswort">Schlusswort</h3>
<p>Mit einer solchen Struktur und Herangehensweise lässt sich auch in einem kleinen Forschungsteam eine professionelle Dokumentation erzielen, die den Prinzipien von Open Science und nachhaltiger Softwareentwicklung gerecht wird. Die investierte Mühe wird durch Zeitgewinn bei Wiederverwendung und Erweiterung der Software mehr als aufgewogen. So wird die Forschungssoftware nicht zum einmaligen “Nebenprodukt”, sondern zu einem robusten, teilbaren Ergebnis wissenschaftlicher Arbeit.</p>
</section>
</section>
<div id="quarto-appendix" class="default"><section class="quarto-appendix-contents" role="doc-bibliography" id="quarto-bibliography"><h2 class="anchored quarto-appendix-heading">Literatur</h2><div id="refs" class="references csl-bib-body" data-entry-spacing="0" role="list">
<div id="ref-prlic2012ten" class="csl-entry" role="listitem">
<div class="csl-left-margin">1. </div><div class="csl-right-inline">Prlić, Andreas, und James B Procter. 2012. Ten simple rules for documenting scientific software. <em>PLoS Computational Biology</em> 8. Public Library of Science: e1002802.</div>
<div id="quarto-appendix" class="default"><section id="referenz-websitesservices" class="level2 appendix"><h2 class="anchored quarto-appendix-heading">Referenz Websites/Services</h2><div class="quarto-appendix-contents">
<ul>
<li><a href="https://github.com" title="Seite mit sehr vielen Open-Source-Projekten, die git verwenden. Gehört zu Microsoft">GitHub</a>: Seite mit sehr vielen Open-Source-Projekten, die git verwenden. Gehört zu Microsoft</li>
<li><a href="https://gitlab.com" title="Open-Source-Lösung für selbst gehostete Projektverwaltung (git, issue-tracking, …). Community (kostenfrei; limitierte features) oder Enterprise-Linzenz">GitLab</a>: Open-Source-Lösung für selbst gehostete Projektverwaltung (git, issue-tracking, …). Community (kostenfrei; limitierte features) oder Enterprise-Linzenz</li>
</ul>
</div></section><section id="referenz-software" class="level2 appendix"><h2 class="anchored quarto-appendix-heading">Referenz Software</h2><div class="quarto-appendix-contents">
<ul>
<li><a href="https://git-scm.com" title="Versionskontrollsystem">git</a>: Versionskontrollsystem</li>
<li><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>: Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg</li>
<li><a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>: Mittlerweile DER Standard bei plaintext-Dokumenten</li>
<li><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>: Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden</li>
<li><a href="https://pandoc.org/MANUAL.html#pandocs-markdown" title="DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln und hieraus HTML/PDF u.ä. erstellen">pandoc</a>: DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln und hieraus HTML/PDF u.ä. erstellen</li>
<li><a href="https://en.wikipedia.org/wiki/ReStructuredText" title="Alternative zu Markdown.">rst</a>: Alternative zu Markdown.</li>
</ul>
</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">
<div id="ref-PrlicProcter2012TenSimpleRules" class="csl-entry" role="listitem">
<div class="csl-left-margin">1. </div><div class="csl-right-inline">Prlić, Andreas, und James B. Procter. 2012. Ten <span>Simple Rules</span> for the <span>Open Development</span> of <span>Scientific Software</span>. <em>PLOS Computational Biology</em> 8. Public Library of Science: e1002802. <a href="https://doi.org/10.1371/journal.pcbi.1002802">https://doi.org/10.1371/journal.pcbi.1002802</a>.</div>
</div>
<div id="ref-wilson2017good" class="csl-entry" role="listitem">
<div class="csl-left-margin">2. </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.</div>
<div id="ref-WilsonEtAl2017Goodenoughpractices" class="csl-entry" role="listitem">
<div class="csl-left-margin">2. </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-katz2021open" class="csl-entry" role="listitem">
<div class="csl-left-margin">3. </div><div class="csl-right-inline">Katz, Daniel S, Kyle E Niemeyer, und Arfon M Smith. 2021. The Journal of Open Source Software (JOSS). <em>PeerJ Computer Science</em> 7. PeerJ Inc.: e432.</div>
<div id="ref-BarkerEtAl2022IntroducingFAIR" class="csl-entry" role="listitem">
<div class="csl-left-margin">3. </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-endings2020principles" class="csl-entry" role="listitem">
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Endings Project. 2020. <a href="https://endings.uvic.ca/principles.html">Endings Principles for Digital Longevity</a>.</div>
<div id="ref-EndingsPrinciples221" class="csl-entry" role="listitem">
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Endings Project Team. 2023. <a href="https://endings.uvic.ca/principles.html">Endings <span>Principles</span> for <span>Digital Longevity</span></a>.</div>
</div>
<div id="ref-smith2016software" class="csl-entry" role="listitem">
<div class="csl-left-margin">5. </div><div class="csl-right-inline">Smith, Arfon M, Daniel S Katz, Kyle E Niemeyer, FORCE11 Software Citation Working Group, u. a. 2016. Software citation principles. <em>PeerJ Computer Science</em> 2. PeerJ Inc.: e86.</div>
<div id="ref-SmithEtAl2016Softwarecitation" 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-maria2019jupyter" class="csl-entry" role="listitem">
<div class="csl-left-margin">6. </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 notebooks—a publishing format for reproducible computational workflows. <em>Positioning and Power in Academic Publishing: Players, Agents and Agendas</em> 20. IOS Press: 87–90.</div>
<div id="ref-KluyverEtAl2016JupyterNotebookspublishing" class="csl-entry" role="listitem">
<div class="csl-left-margin">6. </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 <em>20th <span>International Conference</span> on <span>Electronic Publishing</span> (01/01/16)</em>, 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></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 , GPT-4.5},

192
background/BACKGROUND.md
View File

@ -71,8 +71,8 @@ gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware
**auffindbar, nachvollziehbar und wiederverwendbar** zu machen.
[Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien
[@PrlicProcter2012TenSimpleRules; @WilsonEtAl2017Goodenoughpractices; @BarkerEtAl2022IntroducingFAIR;
@EndingsPrinciples221].]{.aside}
[@PrlicProcter2012TenSimpleRules; @WilsonEtAl2017Goodenoughpractices;
@BarkerEtAl2022IntroducingFAIR; @EndingsPrinciples221].]{.aside}
Dieser Anforderungskatalog richtet sich an Forschende, die keine
Vollzeit-Programmierer sind, und soll **wissenschaftlich fundierte Richtlinien**
@ -120,10 +120,10 @@ umfasst die **Datenmodelle** (etwa wichtige Felder, deren Bedeutung und
kontrollierte Vokabulare) und Annahmen über die Daten. Gemäß den
ENDINGS-Prinzipien sollte die Datenstruktur in einem _statischen Dokument_
festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie
die Software die Daten interpretiert. Eine Tabelle oder Auflistung der
Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht die Klarheit.
[Beispiel: _“Eingabedatei: CSV mit Spalten `Autor`, `Empfänger`, ...; Ausgabe:
JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”_]{.aside}
die Software die Daten interpretiert [@EndingsPrinciples221]. Eine Tabelle oder
Auflistung der Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht
die Klarheit. [Beispiel: _“Eingabedatei: CSV mit Spalten `Autor`, `Empfänger`,
...; Ausgabe: JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”_]{.aside}
### Code-Abhängigkeiten und technische Voraussetzungen
@ -221,12 +221,13 @@ Nachnutzung nicht zu behindern. Zudem sollte angegeben werden, wie die Software
_“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 [@SmithEtAl2016Softwarecitation]. Schließlich
ist es sinnvoll, eine **Versionsnummer** 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. Diese Praxis entspricht auch den ENDINGS-Prinzipien, die verlangen, dass
jede veröffentlichte Version eindeutig erkennbar ist und zitiert werden kann.
Autor\*innen Credits für ihre Software bekommen
[@SmithEtAl2016Softwarecitation]. Schließlich ist es sinnvoll, eine
**Versionsnummer** 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. Diese Praxis
entspricht auch den ENDINGS-Prinzipien, die verlangen, dass jede veröffentlichte
Version eindeutig erkennbar ist und zitiert werden kann.
### Zusammenfassung der inhaltlichen Anforderungen
@ -251,13 +252,14 @@ Die Hauptdokumentation sollte als README in Markdown-Format im Hauptverzeichnis
des Code-Repositoriums liegen. Dieses README fungiert als “Startseite” des
Projekts und enthält idealerweise eine komprimierte Übersicht aller wichtigen
Punkte: Zweck der Software, Kurzbeschreibung, Installation, kurzer
Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie GitHub, GitLab etc. wird
die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die Vorteile von
**Markdown** sind die einfache Lesbarkeit in Rohform, die breite Unterstützung
(auch in Renderern wie GitHub-Webansicht) und die Eignung für Versionierung
(Textdatei im Git). So bleibt die Dokumentation eng mit dem Code verzahnt und
unter Versionskontrolle – ein Prinzip, das auch von ENDINGS propagiert wird
(Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden).
Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie [GitHub][], [GitLab][]
etc. wird die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die
Vorteile von **[Markdown][]** sind die einfache Lesbarkeit in Rohform, die
breite Unterstützung (auch in Renderern wie GitHub-Webansicht) und die Eignung
für Versionierung (Textdatei im [git][]). So bleibt die Dokumentation eng mit
dem Code verzahnt und unter Versionskontrolle – ein Prinzip, das auch von
ENDINGS[@EndingsPrinciples221] propagiert wird (Dokumentation soll statisch und
zusammen mit den Daten/Code abgelegt werden).
### Strukturierte Unterteilung in weitere Dateien/Abschnitte
@ -289,7 +291,7 @@ Beispielhafter Struktur eines Code-Repositories
Sollte die Dokumentation umfangreicher sein, ist es sinnvoll, sie in logisch
getrennte Abschnitte aufzuteilen. Dies kann innerhalb der README durch
Überschriften geschehen oder durch **zusätzliche Markdown-Dateien** im
Überschriften geschehen oder durch **zusätzliche [Markdown][]-Dateien** im
Repository (z. B. eine `INSTALL.md` für ausführliche Installationshinweise, eine
`USAGE.md` oder `TUTORIAL.md` für detaillierte Benutzeranleitungen, eine
`CHANGELOG.md` für Changelog etc.). Eine gängige Struktur ist z. B.:
@ -303,7 +305,7 @@ Repository (z. B. eine `INSTALL.md` für ausführliche Installationshinweise,
Diese Dateien sollten konsistent formatiert und benannt sein, damit sie leicht
auffindbar sind. Sie kommen ohne spezielle Tools aus – ein einfacher Texteditor
genügt zum Bearbeiten. Auch **Wiki-Seiten** (etwa in GitHub) können genutzt
genügt zum Bearbeiten. Auch **Wiki-Seiten** (etwa in [GitHub][]) können genutzt
werden, sind aber weniger dauerhaft versioniert im Vergleich zu Dateien im
Code-Repository selbst. Die Dokumentation sollte möglichst _im Repository_
selbst liegen, um sicherzustellen, dass sie gemeinsam mit dem Code versioniert,
@ -313,43 +315,36 @@ Projekte oft Overkill und können im schlimmsten Fall verwaisen.
### Keine proprietären Formate oder Abhängigkeit von Werkzeugen
Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten,
sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown,
reStructuredText). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente
oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht
diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil
des Versionskontrollsystems. Ein Markdown-Dokument hingegen kann gemeinsam mit
dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Zudem
erlauben offene Formate eine leichtere **Langzeitarchivierung**: Gemäß
Endings-Prinzip sollten Informationsressourcen in langfristig lesbaren Formaten
vorliegen. Markdown/Plaintext erfüllt diese Bedingung (im Gegensatz etwa zu
einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10
Jahren evtl. nicht mehr läuft). Im Sinne der _Digital Longevity_ ist eine
**statische HTML- oder PDF-Version** der Dokumentation (automatisch generiert
aus Markdown) als Teil der Release-Artefakte sinnvoll – so kann z. B. in jeder
veröffentlichten Version ein PDF-Handbuch beigelegt werden, das später zitiert
oder referenziert werden kann. **Wichtig ist aber, dass die Quelle der Wahrheit
immer die im Repository gepflegte Doku bleibt.**
sollte auf gängige, offene Formate gesetzt werden (Plaintext, [Markdown][],
[reStructuredText][rst]). Vermeiden Sie nach Möglichkeit Formate wie
Word-Dokumente oder PDF als primäre Dokumentationsquelle – solche Formate sind
nicht diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht
Teil des Versionskontrollsystems. Ein [Markdown][]-Dokument hingegen kann
gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent
nachvollziehbar. Markdown/Plaintext erfüllt die Bedingung der offenen
**Langzeitarchivierung**[@EndingsPrinciples221] (im Gegensatz etwa zu einer
Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 Jahren
evtl. nicht mehr läuft). Im Sinne der _Digital Longevity_ ist eine **statische
HTML- oder PDF-Version** der Dokumentation (automatisch generiert aus
[Markdown][] via [pandoc][]) als Teil der Release-Artefakte sinnvoll. **Wichtig
ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku
bleibt.**
### Übersichtlichkeit und Navigierbarkeit
Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit
Leser schnell die gesuchten Informationen finden. Eine **logische Gliederung**
(wie in diesem Katalog: Einführung, Anforderungen, Installation, Nutzung,
Hintergrund, etc.) hilft unterschiedlichen Nutzergruppen gezielt das Relevante
zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine
Abschnittsübersicht am Anfang nützlich sein. Markdown bietet z. B. automatische
Toc-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur
zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an
einem Ort). Wiederholungen sollten vermieden werden: lieber an einer Stelle
ausführlich dokumentieren und sonst darauf verweisen, um Konsistenzprobleme zu
vermeiden (_"Don’t Repeat Yourself"_ gilt auch für Dokumentation). Bei ähnlichen
Projekten können Sie sich an bestehenden **Dokumentationsvorlagen** orientieren:
Viele erfolgreiche Open-Source-Projekte haben auf GitHub eine ähnliche
README-Struktur, die als informelles Template dienen kann.
hilft unterschiedlichen Nutzergruppen gezielt das Relevante zu finden. Für
längere Dokumente kann ein Inhaltsverzeichnis oder eine Abschnittsübersicht am
Anfang nützlich sein. [Markdown][] bietet z. B. automatische TOC-Generierung auf
manchen Plattformen. Achten Sie darauf, pro Abschnitt nur zusammenhängende
Informationen zu behandeln (z. B. alles zu Installation an einem Ort) und
Wiederholungen zu vermeiden. Das Mantra _"Don’t Repeat Yourself"_ gilt auch für
Dokumentation.
### Beispiele, Codeblöcke und ggf. Abbildungen einbinden
Nutzen Sie die Möglichkeiten von Markdown, um die Dokumentation lebendig zu
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
(etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche,
@ -357,22 +352,30 @@ etc.). 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 (zur Not handgezeichnet und abfotografiert, besser
jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder Graphviz). 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 **prinzip “keep it simple”**
abzuweichen.
jedoch mit Tools wie [mermaid.js][] Diagrammen in [Markdown][] oder
[graphviz][]). 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 **Prinzip
“keep it simple”** abzuweichen.
### Fazit Format und Struktur
Insgesamt gilt: **Die Dokumentation sollte im gleichen Repository leben wie der
Code, klar strukturiert und in einem einfach handhabbaren Format vorliegen.**
Sie soll ohne spezielle Umgebung lesbar sein – ein Nutzer, der das Repository
klont oder herunterlädt, muss sofort Zugang zur Dokumentation haben. Dieses
Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software
(und deren Doku) _auffindbar_ und _zugänglich_ zu machen, ohne Hürden. Eine gut
gepflegte README in Markdown erfüllt diese Anforderungen in den meisten Fällen
optimal.
Insgesamt gilt: Die Dokumentation sollte
- im gleichen Repository leben wie der Code
- klar strukturiert und in einem einfach handhabbaren Format vorliegen
- ohne spezielle Umgebung lesbar sein
Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern,
Software (und deren Doku) _auffindbar_ und _zugänglich_ zu machen, ohne Hürden.
Eine **gut gepflegte** README in [Markdown][] erfüllt diese Anforderungen in den
meisten Fällen optimal.
<!--
Markierung für mich -.-
-->
## Umfang und Fokus der Dokumentation
@ -505,15 +508,15 @@ und Einheitlichkeit zu gewährleisten.
### Jupyter Notebooks und literate programming
Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind
**Jupyter Notebooks** bzw. R Markdown Notebooks [@KluyverEtAl2016JupyterNotebookspublishing]. Diese
erlauben es, _ausführbaren Code mit erklärendem Text und Visualisierungen_ in
einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei
leisten: (1) als **Tutorials/Beispiel-Workflows**, die Nutzer interaktiv
nachvollziehen können, und (2) als **Reproduzierbarkeits-Dokumentation** für
analytische Prozesse. Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist,
könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall
durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der
Ergebnisse).
**Jupyter Notebooks** bzw. R Markdown Notebooks
[@KluyverEtAl2016JupyterNotebookspublishing]. Diese erlauben es, _ausführbaren
Code mit erklärendem Text und Visualisierungen_ in einem Dokument zu vereinen.
Für Dokumentationszwecke können Notebooks zweierlei leisten: (1) als
**Tutorials/Beispiel-Workflows**, die Nutzer interaktiv nachvollziehen können,
und (2) als **Reproduzierbarkeits-Dokumentation** für analytische Prozesse. Wenn
Ihre Forschungssoftware z. B. eine Bibliothek ist, könnten Sie ein Notebook
bereitstellen, das einen typischen Anwendungsfall durchspielt (inklusive
Daten-Loading, Aufruf der Funktionen, Darstellung der Ergebnisse).
Notebooks senken die Hürde, weil Nutzer direkt experimentieren können, und
fördern transparente Forschung, da Code, Ergebnisse und Beschreibung
@ -826,3 +829,48 @@ investierte Mühe wird durch Zeitgewinn bei Wiederverwendung und Erweiterung der
Software mehr als aufgewogen. So wird die Forschungssoftware nicht zum
einmaligen “Nebenprodukt”, sondern zu einem robusten, teilbaren Ergebnis
wissenschaftlicher Arbeit.
## Referenz Websites/Services {.appendix}
- [GitHub][]: Seite mit sehr vielen Open-Source-Projekten, die git verwenden.
Gehört zu Microsoft
- [GitLab][]: Open-Source-Lösung für selbst gehostete Projektverwaltung (git,
issue-tracking, …). Community (kostenfrei; limitierte features) oder
Enterprise-Linzenz
## Referenz Software {.appendix}
- [git][]: Versionskontrollsystem
- [graphviz][]: Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf
vielen Systemen verfügbar und rendert zu pdf/svg
- [Markdown][]: Mittlerweile DER Standard bei plaintext-Dokumenten
- [mermaid.js][]: Sprache für Diagramme; kann automatisiert (z.b. durch pandoc,
javascript im HTML, …) in Bilder gewandelt werden
- [pandoc][]: DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln
und hieraus HTML/PDF u.ä. erstellen
- [rst][]: Alternative zu Markdown.
[git]: https://git-scm.com "Versionskontrollsystem"
[GitHub]:
https://github.com
"Seite mit sehr vielen Open-Source-Projekten, die git verwenden. Gehört zu Microsoft"
[GitLab]:
https://gitlab.com
"Open-Source-Lösung für selbst gehostete Projektverwaltung (git, issue-tracking, …).
Community (kostenfrei; limitierte features) oder Enterprise-Linzenz"
[graphviz]:
https://graphviz.org/
"Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg"
[Markdown]:
https://en.wikipedia.org/wiki/Markdown
"Mittlerweile DER Standard bei plaintext-Dokumenten"
[mermaid.js]:
https://mermaid.js.org/
"Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden"
[pandoc]:
https://pandoc.org/MANUAL.html#pandocs-markdown
"DER Konverter für Dokumente. Kann sehr viel in Markdown
wandeln und hieraus HTML/PDF u.ä. erstellen"
[rst]: https://en.wikipedia.org/wiki/ReStructuredText "Alternative zu Markdown."
## Bibliographie {.appendix}

455
background/background.bib
View File

@ -1,39 +1,55 @@
% this bibliography is maintained in Zotero with the tag 'project: documentation'
% prefered format is BibLaTeX
@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},
@article{SmithEtAl2016Softwarecitation,
title = {Software Citation Principles},
author = {Smith, Arfon M. and Katz, Daniel S. and Niemeyer, Kyle E.},
year = {2016},
journal = {PeerJ Computer Science},
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},
keywords = {field: History,project: documentation,Project: Methods Lab 🥼}
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}
}
% == BibTeX quality report for SmithEtAl2016Softwarecitation:
% ? unused Journal abbreviation ("PeerJ Comput. Sci.")
% ? unused Library catalog ("peerj.com")
@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},
keywords = {Digital Scholarly Editions,project: documentation,Project: Methods Lab 🥼,TEI: Text Encoding Initiative}
@book{Kemman2021Trading,
title = {Trading {{Zones}} of {{Digital History}}},
author = {Kemman, Max},
year = {2021},
journal = {Trading Zones of Digital History},
series = {Studies in {{Digital History}} and {{Hermeneutics}}},
number = {1},
publisher = {De Gruyter Oldenbourg},
address = {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},
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}
}
% == BibTeX quality report for Kemman2021Trading:
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.degruyter.com")
% ? unused Number of pages ("182")
@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},
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},
year = {2022},
month = oct,
journal = {Scientific Data},
volume = {9},
number = {1},
pages = {622},
@ -43,180 +59,22 @@
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.},
copyright = {2022 The Author(s)},
langid = {english},
keywords = {project: documentation,Project: Methods Lab 🥼,RSE: Research Software Engineering}
}
@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},
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab 🥼}
}
@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},
keywords = {project: documentation,Project: Methods Lab 🥼}
}
@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},
version = {2.2.1},
keywords = {project: documentation,Project: Methods Lab 🥼,Project: Tool Registry 🧰,talk: 2024 Bochum,writing: 2024 Tool Registry}
}
@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},
version = {1.2},
keywords = {project: documentation,Project: Methods Lab 🥼}
}
@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},
pagetotal = {182},
keywords = {Digital History,Eintrag bereinigt,PDF (Dropbox),project: documentation,TH-MA-Bloomsbury}
}
@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},
keywords = {project: documentation,Project: Methods Lab 🥼}
}
@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},
keywords = {project: documentation,Project: Methods Lab 🥼}
}
@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},
keywords = {project: documentation,Project: Methods Lab 🥼}
}
@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},
keywords = {project: documentation,Project: Methods Lab 🥼}
}
@article{SmithEtAl2016Softwarecitation,
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},
keywords = {Eintrag bereinigt,PDF (Dropbox),project: documentation,Project: Methods Lab 🥼,Research Software Engineering}
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}
}
% == BibTeX quality report for BarkerEtAl2022IntroducingFAIR:
% ? unused Journal abbreviation ("Sci Data")
% ? unused Library catalog ("www.nature.com")
@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},
year = {2017},
month = jun,
journal = {PLOS Computational Biology},
volume = {13},
number = {6},
pages = {e1005510},
@ -227,5 +85,206 @@
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},
keywords = {project: documentation,Project: Methods Lab 🥼}
language = {en},
keywords = {Computer software,Control systems,Data management,Metadata,Programming languages,project: documentation,Project: Methods Lab,Reproducibility,Software tools,Source code}
}
% == BibTeX quality report for WilsonEtAl2017Goodenoughpractices:
% ? unused Library catalog ("PLoS Journals")
@article{Lee2018Tensimplerules,
title = {Ten Simple Rules for Documenting Scientific Software},
author = {Lee, Benjamin D.},
year = {2018},
month = dec,
journal = {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}
}
% == BibTeX quality report for Lee2018Tensimplerules:
% ? unused Library catalog ("PLoS Journals")
@inproceedings{KluyverEtAl2016JupyterNotebookspublishing,
title = {Jupyter {{Notebooks}} -- a Publishing Format for Reproducible Computational Workflows},
booktitle = {20th {{International Conference}} on {{Electronic Publishing}} (01/01/16)},
author = {Kluyver, Thomas and {Ragan-Kelley}, Benjamin and P{\'e}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{\'a}n and Abdalla, Safia and Willing, Carol and {Jupyter development team}},
editor = {Loizides, Fernando and Scmidt, Birgit},
year = {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.},
collaborator = {Kluyver, Thomas and {Ragan-Kelley}, Benjamin and P{\'e}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{\'a}n and Abdalla, Safia and Willing, Carol and {Jupyter development team} and Loizides, Fernando and Scmidt, Birgit},
copyright = {cc\_by\_4},
langid = {english},
language = {en},
keywords = {project: documentation,Project: Methods Lab}
}
% == BibTeX quality report for KluyverEtAl2016JupyterNotebookspublishing:
% ? Unsure about the formatting of the booktitle
% ? unused Library catalog ("eprints.soton.ac.uk")
@misc{EndingsPrinciples221,
title = {Endings {{Principles}} for {{Digital Longevity}}},
shorttitle = {Endings {{Principles}}},
author = {{Endings Project Team}},
year = {2023},
month = mar,
url = {https://endings.uvic.ca/principles.html},
urldate = {2024-05-14},
abstract = {Enabling Sustainable Digital Humanities Projects},
langid = {english},
language = {en},
keywords = {project: documentation,Project: Methods Lab,Project: Tool Registry,talk: 2024 Bochum,writing: 2024 Tool Registry}
}
% == BibTeX quality report for EndingsPrinciples221:
% ? Title looks like it was stored in title-case in Zotero
% ? unused Version number ("2.2.1")
@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 {van de Sandt}, Stephanie 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},
year = {2020},
month = jun,
journal = {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}
}
% == BibTeX quality report for lamprecht2020towards:
% ? unused Library catalog ("SAGE Journals")
@book{CremerEtAl2024Projektmanagement,
title = {{Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit}},
editor = {Cremer, Fabian and Dogunke, Swantje and Neubert, Anna Maria and W{\"u}bbena, Thorsten},
year = {2024},
month = apr,
publisher = {Bielefeld University Press},
address = {Bielefeld},
doi = {10.14361/9783839469675},
urldate = {2024-06-03},
abstract = {Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.},
copyright = {CC BY 4.0},
langid = {ngerman},
language = {de},
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab}
}
@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.},
year = {2025},
month = feb,
journal = {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.},
langid = {english},
language = {eng},
keywords = {project: documentation,Project: Methods Lab}
}
% == BibTeX quality report for DiehlEtAl2025JournalOpenSource:
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.iastatedigitalpress.com")
@article{PrlicProcter2012TenSimpleRules,
title = {Ten {{Simple Rules}} for the {{Open Development}} of {{Scientific Software}}},
author = {Prli{\'c}, Andreas and Procter, James B.},
year = {2012},
month = dec,
journal = {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}
}
% == BibTeX quality report for PrlicProcter2012TenSimpleRules:
% ? Title looks like it was stored in title-case in Zotero
% ? 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},
year = {2023},
series = {Cambridge {{Elements}}: {{Historical Theory}} and {{Practice}}},
publisher = {Cambridge University Press},
address = {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},
copyright = {CC BY-NC-ND 4.0},
langid = {english},
language = {en},
keywords = {field: History,project: documentation,Project: Methods Lab}
}
% == BibTeX quality report for AhnertEtAl2023CollaborativeHistoricalResearch:
% ? Title looks like it was stored in title-case in Zotero
@misc{Forschungsgemeinschaft2025LeitlinienzurSicherung,
title = {{Leitlinien zur Sicherung guter wissenschaftlicher Praxis}},
year = {2024},
month = sep,
publisher = {Deutsche Forschungsgemeinschaft},
doi = {10.5281/zenodo.14281892},
url = {https://zenodo.org/records/14281892},
urldate = {2025-05-15},
abstract = {The DFG{\textasciiacute}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},
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 Integritat,wissenschaftliches Fehlverhalten}
}
% == BibTeX quality report for Forschungsgemeinschaft2025LeitlinienzurSicherung:
% ? unused Committee ("Team „Wissenschaftliche Integrität“")
% ? unused Library catalog ("Zenodo")
% ? unused Version number ("1.2")
@techreport{AltenhonerEtAl2023DFGPraxisregeln,
title = {{DFG-Praxisregeln "Digitalisierung". Aktualisierte Fassung 2022.}},
author = {Altenh{\"o}ner, Reinhard and Berger, Andreas and Bracht, Christian and Klimpel, Paul and Meyer, Sebastian and Neuburger, Andreas and St{\"a}cker, Thomas and Stein, Regine},
year = {2023},
month = feb,
url = {https://zenodo.org/record/7435724},
urldate = {2023-03-07},
abstract = {Die DFG-Praxisregeln ,,Digitalisierung`` stellen eine zentrale Grundlage f{\"u}r DFG-gef{\"o}rderte Projekte im Programm ,,Digitalisierung und Erschlie{\ss}ung`` dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschlie{\ss}ung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zug{\"a}nglichkeit und Anschlussf{\"a}higkeit gef{\"o}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{\"a}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 {\"u}berarbeitet vorliegenden Praxisregeln ,,Digitalisierung`` dienen als Ausgangspunkt f{\"u}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,Erschliessung,Informationsinfrastrukturen,NFDI,Praxisregeln,project: documentation,Project: Methods Lab,Standardbildung,TEI: Text Encoding Initiative}
}
% == BibTeX quality report for AltenhonerEtAl2023DFGPraxisregeln:
% Missing required field 'institution'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("Zenodo")