mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-07 17:44:01 +00:00
minor correction with citation.
This commit is contained in:
Nicole Dresselhaus
parent
1dd2310caa
commit
6d7f7f3dfa
@ -2312,13 +2312,13 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
<section id="einleitung" class="level2">
|
||||
<h2 class="anchored" data-anchor-id="einleitung">Einleitung</h2>
|
||||
<p>Die <strong>Dokumentation von Forschungssoftware</strong> ist entscheidend, um wissenschaftliche Ergebnisse nachvollziehbar und Software für andere nutzbar zu machen. Insbesondere in den Digital Humanities (etwa in der Geschichtswissenschaft) entwickeln Forschende neben Forschung und Lehre oft eigene Software – meist unter hohem Zeitdruck und ohne formale Ausbildung in Softwareentwicklung. Häufig bleibt die Dokumentation deshalb minimal oder unvollständig, was dazu führt, dass andere (und sogar die Autor*innen selbst) viel Zeit aufwenden müssen, um den Code zu verstehen und anzuwenden. Dabei gilt gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware <strong>auffindbar, nachvollziehbar und wiederverwendbar</strong> zu machen.</p>
|
||||
<p>Dieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll <strong>wissenschaftlich fundierte Richtlinien</strong> für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering <a href="@Hasselbring2020OpenSourceResearch;%20@Lee2018Tensimplerules">RSE</a> und damit einhergehender Prinzipien wie die des <em>Endings-Projekts</em> für digitale Langlebigkeit <span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> und <em>FAIR4RS-Prinzipien</em><span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">2</a>]</span>.</p>
|
||||
<p>Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die <strong>Nachvollziehbarkeit</strong> der Ergebnisse als auch eine <strong>Weiterverwendung</strong> der Software zu ermöglichen<span class="citation" data-cites="Wilson2017GoodEnoughPractices">[<a href="#ref-Wilson2017GoodEnoughPractices" role="doc-biblioref">3</a>]</span>.</p>
|
||||
<p>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 <span class="citation" data-cites="Hasselbring2020OpenSourceResearch Lee2018Tensimplerules">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">1</a>, <a href="#ref-Lee2018Tensimplerules" role="doc-biblioref">2</a>]</span> und damit einhergehender Prinzipien wie die des <em>Endings-Projekts</em> für digitale Langlebigkeit <span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>]</span> und <em>FAIR4RS-Prinzipien</em><span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">4</a>]</span>.</p>
|
||||
<p>Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die <strong>Nachvollziehbarkeit</strong> der Ergebnisse als auch eine <strong>Weiterverwendung</strong> der Software zu ermöglichen<span class="citation" data-cites="Wilson2017GoodEnoughPractices">[<a href="#ref-Wilson2017GoodEnoughPractices" role="doc-biblioref">5</a>]</span>.</p>
|
||||
<p>Im Folgenden werden die Anforderungen an Inhalt, Format und Umfang der Dokumentation definiert, geeignete (teil-)automatisierte Dokumentationswerkzeuge diskutiert und Best Practices in Form von Vorlagen und Checklisten vorgestellt.</p>
|
||||
</section>
|
||||
<section id="inhaltliche-anforderungen-an-die-dokumentation" class="level2 page-columns page-full">
|
||||
<h2 class="anchored" data-anchor-id="inhaltliche-anforderungen-an-die-dokumentation">Inhaltliche Anforderungen an die Dokumentation</h2>
|
||||
<p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="EndingsPrinciples221 Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>, <a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">4</a>]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
|
||||
<p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="EndingsPrinciples221 Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>, <a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">6</a>]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
|
||||
<section id="ziel-und-zweck-der-software-statement-of-need" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="ziel-und-zweck-der-software-statement-of-need">Ziel und Zweck der Software (Statement of Need)</h3>
|
||||
<div class="page-columns page-full"><p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em></span></div></div>
|
||||
@ -2327,7 +2327,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
<h3 class="anchored" data-anchor-id="input-output-spezifikation-und-datenbeschreibung">Input-/Output-Spezifikation und Datenbeschreibung</h3>
|
||||
<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.</p>
|
||||
<p>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.</p>
|
||||
<div class="page-columns page-full"><p>Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch 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">1</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>
|
||||
<div class="page-columns page-full"><p>Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch 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">3</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>
|
||||
<p>Gerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via <a href="https://json-schema.org/draft/2020-12/json-schema-core">JSON-Schema</a> an.</p>
|
||||
</section>
|
||||
<section id="code-abhängigkeiten-und-technische-voraussetzungen" class="level3 page-columns page-full">
|
||||
@ -2358,9 +2358,9 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
<div class="no-row-height column-margin column-container"><div id="fn2"><p><sup>2</sup> Dieser Aspekt muss nicht umfangreich sein, zeigt aber Offenheit und sorgt dafür, dass im Falle von Rückfragen die Hürde für Kontaktaufnahme niedrig ist.</p></div></div></section>
|
||||
<section id="projekt-metadaten-lizenz-zitation-version" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="projekt-metadaten-lizenz-zitation-version">Projekt-Metadaten (Lizenz, Zitation, Version)</h3>
|
||||
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten<span class="citation" data-cites="Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">4</a>]</span>. <strong>Lizenzinformationen</strong> klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine <strong>LICENSE-Datei</strong> beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.</p>
|
||||
<p>Zudem sollte angegeben werden, wie die Software <strong>zitiert</strong> werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt <em>“Zitation”</em> oder eine <strong>CITATION-Datei</strong> beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen <span class="citation" data-cites="Smith2016SoftwareCitationPrinciples">[<a href="#ref-Smith2016SoftwareCitationPrinciples" role="doc-biblioref">5</a>]</span>.</p>
|
||||
<p>Schließlich ist es sinnvoll, eine <strong>Versionsnummer</strong> der Software zu nennen (idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen gibt<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span>.</p>
|
||||
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten<span class="citation" data-cites="Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">6</a>]</span>. <strong>Lizenzinformationen</strong> klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine <strong>LICENSE-Datei</strong> beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.</p>
|
||||
<p>Zudem sollte angegeben werden, wie die Software <strong>zitiert</strong> werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt <em>“Zitation”</em> oder eine <strong>CITATION-Datei</strong> beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen <span class="citation" data-cites="Smith2016SoftwareCitationPrinciples">[<a href="#ref-Smith2016SoftwareCitationPrinciples" role="doc-biblioref">7</a>]</span>.</p>
|
||||
<p>Schließlich ist es sinnvoll, eine <strong>Versionsnummer</strong> der Software zu nennen (idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen gibt<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>]</span>.</p>
|
||||
</section>
|
||||
<section id="zusammenfassung-der-inhaltlichen-anforderungen" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="zusammenfassung-der-inhaltlichen-anforderungen">Zusammenfassung der inhaltlichen Anforderungen</h3>
|
||||
@ -2401,7 +2401,7 @@ Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantwor
|
||||
<li>kurzer Nutzungsbeispiel,</li>
|
||||
<li>Kontakt/Lizenz.</li>
|
||||
</ul>
|
||||
<p>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="Das de-facto Standard-Versionskontrollsystem">git</a>). So bleibt die Dokumentation eng mit dem Code verzahnt und unter Versionskontrolle – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span>.</p>
|
||||
<p>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="Das de-facto Standard-Versionskontrollsystem">git</a>). So bleibt die Dokumentation eng mit dem Code verzahnt und unter Versionskontrolle – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>]</span>.</p>
|
||||
</section>
|
||||
<section id="keine-proprietären-formate-oder-abhängigkeit-von-werkzeugen" class="level3 page-columns page-full">
|
||||
<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>
|
||||
@ -2420,7 +2420,7 @@ Prinzip
|
||||
</div>
|
||||
</div></div><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>).</p>
|
||||
<p><span class="bad-practice">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.</span> 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.</p>
|
||||
<p>Im Sinne der <em>Digital Longevity</em><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> 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>
|
||||
<p>Im Sinne der <em>Digital Longevity</em><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>]</span> 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="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>
|
||||
@ -2567,7 +2567,7 @@ Prinzip
|
||||
<p>Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwickler*innendokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, oder sogar automatisch erzeugt werden.</p>
|
||||
<section id="minimaldokumentation-kurze-kommentare" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="minimaldokumentation-kurze-kommentare">Minimaldokumentation: kurze Kommentare</h4>
|
||||
<p>Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (<em>“keine Dokumentation”</em> ist keine Option). <em>Good Enough Practices</em><span class="citation" data-cites="Wilson2017GoodEnoughPractices">[<a href="#ref-Wilson2017GoodEnoughPractices" role="doc-biblioref">3</a>]</span> empfehlen, als ersten Schritt zumindest einen <strong>kurzen erklärenden Kommentar am Anfang jedes Scripts</strong> oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. Später kann die Dokumentation erweitert werden, insbesondere wenn die Software in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B. durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst <em>klein</em> anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte 30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).</p>
|
||||
<p>Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (<em>“keine Dokumentation”</em> ist keine Option). <em>Good Enough Practices</em><span class="citation" data-cites="Wilson2017GoodEnoughPractices">[<a href="#ref-Wilson2017GoodEnoughPractices" role="doc-biblioref">5</a>]</span> empfehlen, als ersten Schritt zumindest einen <strong>kurzen erklärenden Kommentar am Anfang jedes Scripts</strong> oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. Später kann die Dokumentation erweitert werden, insbesondere wenn die Software in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B. durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst <em>klein</em> anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte 30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).</p>
|
||||
</section>
|
||||
<section id="verlinkte-dokumentation-ist-auch-dokumentation" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="verlinkte-dokumentation-ist-auch-dokumentation">Verlinkte Dokumentation ist auch Dokumentation</h4>
|
||||
@ -2583,7 +2583,7 @@ Prinzip
|
||||
<h2 class="anchored" data-anchor-id="was-macht-eine-gute-dokumentation-aus">Was macht eine gute Dokumentation aus</h2>
|
||||
<section id="formelle-prinzipien-open-source-research-fair4rs-und-endings" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="formelle-prinzipien-open-source-research-fair4rs-und-endings">Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS</h3>
|
||||
<p>Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des <strong>Research Software Engineering</strong><span class="citation" data-cites="Hasselbring2020OpenSourceResearch">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">6</a>]</span> und den <strong>FAIR4RS-<span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">2</a>]</span></strong> bzw. <strong>ENDINGS-Prinzipien</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> steht.</p>
|
||||
<p>Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des <strong>Research Software Engineering</strong><span class="citation" data-cites="Hasselbring2020OpenSourceResearch">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">1</a>]</span> und den <strong>FAIR4RS-<span class="citation" data-cites="BarkerEtAl2022IntroducingFAIR">[<a href="#ref-BarkerEtAl2022IntroducingFAIR" role="doc-biblioref">4</a>]</span></strong> bzw. <strong>ENDINGS-Prinzipien</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>]</span> steht.</p>
|
||||
|
||||
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-note callout-titled" title="FAIR4RS-Prinzipien für Software">
|
||||
<div class="callout-header d-flex align-content-center">
|
||||
@ -2643,7 +2643,7 @@ ENDINGS-Prinzipien
|
||||
<p>Die Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge erheblich senken. Gerade Forschende, die alleine programmieren, können von <strong>(teil-)automatisierter Dokumentation</strong> profitieren, um konsistente und aktuelle Unterlagen zu erhalten, ohne alles von Hand schreiben zu müssen. Im Folgenden werden einige Tools und Möglichkeiten vorgestellt – samt Empfehlungen, <em>wann</em> ihr Einsatz sinnvoll oder notwendig ist:</p>
|
||||
<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. <strong>R Markdown Notebooks</strong> <span class="citation" data-cites="KluyverEtAl2016JupyterNotebookspublishing">[<a href="#ref-KluyverEtAl2016JupyterNotebookspublishing" role="doc-biblioref">7</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:</p>
|
||||
<p>Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind <strong>Jupyter Notebooks</strong> bzw. <strong>R Markdown Notebooks</strong> <span class="citation" data-cites="KluyverEtAl2016JupyterNotebookspublishing">[<a href="#ref-KluyverEtAl2016JupyterNotebookspublishing" role="doc-biblioref">8</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:</p>
|
||||
<ol type="1">
|
||||
<li>als <strong>Tutorials/Beispiel-Workflows</strong>, die Nutzer interaktiv nachvollziehen können, und</li>
|
||||
<li>als <strong>Reproduzierbarkeits-Dokumentation</strong> für analytische Prozesse.</li>
|
||||
@ -2686,7 +2686,7 @@ Prinzip
|
||||
<p>Ab einer Codebasis <code>> einige tausend Zeilen</code> oder <code>>5 nontriviale Module</code> sollte eine generierte Dokumentation bereitstehen.</p>
|
||||
</div>
|
||||
</div></div><p>Für umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll sein, eine <strong>Dokumentationswebsite</strong> zu generieren. Tools wie <em><a href="https://www.sphinx-doc.org" title="Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.">Sphinx</a></em> (zusammen mit ReadTheDocs für Hosting) oder <em><a href="https://www.mkdocs.org/" title="Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown">MkDocs</a></em> erlauben es, aus <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>-Dateien einen ansprechend formatierten HTML-Dokumentationssatz zu bauen. Der Vorteil ist, dass man eine durchsuchbare, verlinkte Doku bekommt, oft mit schönem Layout und zusätzlicher Navigation. Mit <em>Continuous Integration</em> lassen sich diese Seiten bei jedem Git-Push automatisch aktualisieren.</p>
|
||||
<p>Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.</p>
|
||||
<p>Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">3</a>]</span> – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.</p>
|
||||
<div class="page-columns page-full"><p>Solche Tools sind <strong>sinnvoll, wenn die Dokumentation sehr groß oder öffentlich weit verbreitet</strong> ist – z. B. wenn Ihre Software von vielen genutzt wird und Sie ein professionelles Auftreten wünschen, oder wenn Sie die Doku als PDF veröffentlichen möchten. </p><div class="no-row-height column-margin column-container"><span class="margin-aside">In kleinen DH-Projekten ist es oft nicht nötig, extra eine Webseite zu hosten; dennoch kann Sphinx auch lokal HTML/PDF erzeugen, was man dem Repo beilegen kann.</span></div></div>
|
||||
<section id="wann-sollten-sie-eine-statische-website-generieren" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="wann-sollten-sie-eine-statische-website-generieren">Wann sollten Sie eine statische Website generieren?</h4>
|
||||
@ -2710,7 +2710,7 @@ Prinzip
|
||||
</div>
|
||||
</div><div id="fn5"><p><sup>5</sup> kurz für: “Documentation String”</p></div></div><p>Nutzen Sie die Möglichkeit, Dokumentation <em>direkt im Quellcode</em> unterzubringen, z. B. in Form von <strong>Docstrings<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a></strong> (mehrzeilige Strings in Funktionen/Klassen bei Python, <a href="https://roxygen2.r-lib.org/" title="Generator um aus R Docstrings eine Dokumentation zu generieren">Roxygen</a>-Kommentare in R, <a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a>-Kommentare in Java, etc.).</p>
|
||||
<p>Diese dienen doppelt: Zum einen erleichtern sie es Ihnen und Kollegen, den Code beim Lesen zu verstehen, zum anderen können sie von Tools ausgelesen und zu hübschen API-Dokumentationen verarbeitet werden. Idealerweise dokumentieren Sie <em>jede wichtige <strong>oder</strong> von außen sichtbare Funktion, Klasse oder Modul</em> mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.</p>
|
||||
<p>Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. <a href="https://google.github.io/styleguide/">Google Style Guide</a> für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)<span class="citation" data-cites="JimenezEtAl2017FourSimpleRecommendations">[<a href="#ref-JimenezEtAl2017FourSimpleRecommendations" role="doc-biblioref">8</a>]</span>. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa <strong><a href="https://www.pylint.org/" title="Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.">pylint</a></strong>, können die Verwendung erzwingen.</p>
|
||||
<p>Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. <a href="https://google.github.io/styleguide/">Google Style Guide</a> für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)<span class="citation" data-cites="JimenezEtAl2017FourSimpleRecommendations">[<a href="#ref-JimenezEtAl2017FourSimpleRecommendations" role="doc-biblioref">9</a>]</span>. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa <strong><a href="https://www.pylint.org/" title="Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.">pylint</a></strong>, können die Verwendung erzwingen.</p>
|
||||
<p>Mit Tools, wie <strong><a href="https://www.sphinx-doc.org" title="Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.">Sphinx</a></strong>, <strong><a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a></strong>, <strong><a href="https://www.doxygen.nl/" title="Generator um aus C/C++ Docstrings eine Dokumentation zu generieren">Doxygen</a></strong>, <strong><a href="https://www.mkdocs.org/" title="Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown">MkDocs</a></strong>,<strong><a href="https://pdoc.dev/" title="Generator um aus Python Docstrings eine Dokumentation zu generieren">pdoc</a></strong> und vielen weiteren, können aus Docstrings automatisiert Webseiten oder PDF-Handbücher generiert werden. Sie lesen z. B. die Python-Docstrings und erzeuge daraus strukturiert eine Dokumentation; Häufig kann über Erweiterungen auch dritte Dokumentation direkt eingebunden und verlinkt werden.</p>
|
||||
</section>
|
||||
<section id="versionskontrolle-und-kontinuierliche-dokumentationspflege" class="level3 page-columns page-full">
|
||||
@ -2776,7 +2776,7 @@ TODO
|
||||
<h2 class="anchored" data-anchor-id="fazit">Fazit</h2>
|
||||
<p>Die hier präsentierten Anforderungen und Empfehlungen bieten einen <strong>Leitfaden für die Dokumentation von Forschungssoftware</strong> in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale <strong>Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit</strong> zu erreichen.</p>
|
||||
<p>Indem zentrale Inhalte (Ziele, Inputs/Outputs, Hintergrund, etc.) klar dokumentiert, ein nutzerfreundliches Format (README im Repo) gewählt, der Umfang fokussiert gehalten und hilfreiche Tools eingesetzt werden, kann die Dokumentation zur Stärke eines Projekts werden statt einem lästigen Anhängsel.</p>
|
||||
<p>So schließt sich der Kreis zwischen guter <strong>Softwareentwicklung</strong> und guter <strong>Wissenschaft</strong><span class="citation" data-cites="Forschungsgemeinschaft2025LeitlinienzurSicherung">[<a href="#ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" role="doc-biblioref">9</a>, Leitlinie 12]</span>: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch wie die Erfahrung zeigt, zahlen sich diese in Form von <em>Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung</em> der Software aus. Mit diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen – trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: <strong>Gut dokumentierte Forschungscode ist nachhaltige Forschung</strong>.</p>
|
||||
<p>So schließt sich der Kreis zwischen guter <strong>Softwareentwicklung</strong> und guter <strong>Wissenschaft</strong><span class="citation" data-cites="Forschungsgemeinschaft2025LeitlinienzurSicherung">[<a href="#ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" role="doc-biblioref">10</a>, Leitlinie 12]</span>: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch wie die Erfahrung zeigt, zahlen sich diese in Form von <em>Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung</em> der Software aus. Mit diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen – trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: <strong>Gut dokumentierte Forschungscode ist nachhaltige Forschung</strong>.</p>
|
||||
</section>
|
||||
|
||||
|
||||
@ -2891,32 +2891,35 @@ TODO
|
||||
|
||||
|
||||
</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-Hasselbring2020OpenSourceResearch" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">1. </div><div class="csl-right-inline">Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open <span>Source Research Software</span>. <em>Computer</em> 53: 84–88. <a href="https://doi.org/10.1109/MC.2020.2998235">https://doi.org/10.1109/MC.2020.2998235</a>.</div>
|
||||
</div>
|
||||
<div id="ref-Lee2018Tensimplerules" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">2. </div><div class="csl-right-inline">Lee, Benjamin D. 2018. Ten Simple Rules for Documenting Scientific Software. <em>PLOS Computational Biology</em> 14. Public Library of Science: e1006561. <a href="https://doi.org/10.1371/journal.pcbi.1006561">https://doi.org/10.1371/journal.pcbi.1006561</a>.</div>
|
||||
</div>
|
||||
<div id="ref-EndingsPrinciples221" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">1. </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> (Version 2.2.1).</div>
|
||||
<div class="csl-left-margin">3. </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> (Version 2.2.1).</div>
|
||||
</div>
|
||||
<div id="ref-BarkerEtAl2022IntroducingFAIR" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">2. </div><div class="csl-right-inline">Barker, Michelle, Neil P. Chue Hong, Daniel S. Katz, Anna-Lena Lamprecht, Carlos Martinez-Ortiz, Fotis Psomopoulos, Jennifer Harrow, u. a. 2022. Introducing the <span>FAIR Principles</span> for Research Software. <em>Scientific Data</em> 9. Nature Publishing Group: 622. <a href="https://doi.org/10.1038/s41597-022-01710-x">https://doi.org/10.1038/s41597-022-01710-x</a>.</div>
|
||||
<div class="csl-left-margin">4. </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-Wilson2017GoodEnoughPractices" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">3. </div><div class="csl-right-inline">Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. <em>PLOS Computational Biology</em> 13. Public Library of Science: e1005510. <a href="https://doi.org/10.1371/journal.pcbi.1005510">https://doi.org/10.1371/journal.pcbi.1005510</a>.</div>
|
||||
<div class="csl-left-margin">5. </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-Lamprecht2020TowardsFAIRPrinciples" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards <span>FAIR</span> Principles for Research Software. <em>Data Science</em> 3. SAGE Publications: 37–59. <a href="https://doi.org/10.3233/DS-190026">https://doi.org/10.3233/DS-190026</a>.</div>
|
||||
<div class="csl-left-margin">6. </div><div class="csl-right-inline">Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards <span>FAIR</span> Principles for Research Software. <em>Data Science</em> 3. SAGE Publications: 37–59. <a href="https://doi.org/10.3233/DS-190026">https://doi.org/10.3233/DS-190026</a>.</div>
|
||||
</div>
|
||||
<div id="ref-Smith2016SoftwareCitationPrinciples" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">5. </div><div class="csl-right-inline">Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. <em>PeerJ Computer Science</em> 2. PeerJ Inc. <a href="https://doi.org/10.7717/peerj-cs.86">https://doi.org/10.7717/peerj-cs.86</a>.</div>
|
||||
</div>
|
||||
<div id="ref-Hasselbring2020OpenSourceResearch" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">6. </div><div class="csl-right-inline">Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open <span>Source Research Software</span>. <em>Computer</em> 53: 84–88. <a href="https://doi.org/10.1109/MC.2020.2998235">https://doi.org/10.1109/MC.2020.2998235</a>.</div>
|
||||
<div class="csl-left-margin">7. </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-KluyverEtAl2016JupyterNotebookspublishing" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">7. </div><div class="csl-right-inline">Kluyver, Thomas, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, u. a. 2016. Jupyter <span>Notebooks</span> – a Publishing Format for Reproducible Computational Workflows. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. <a href="https://doi.org/10.3233/978-1-61499-649-1-87">https://doi.org/10.3233/978-1-61499-649-1-87</a>.</div>
|
||||
<div class="csl-left-margin">8. </div><div class="csl-right-inline">Kluyver, Thomas, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, u. a. 2016. Jupyter <span>Notebooks</span> – a Publishing Format for Reproducible Computational Workflows. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. <a href="https://doi.org/10.3233/978-1-61499-649-1-87">https://doi.org/10.3233/978-1-61499-649-1-87</a>.</div>
|
||||
</div>
|
||||
<div id="ref-JimenezEtAl2017FourSimpleRecommendations" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">8. </div><div class="csl-right-inline">Jiménez, Rafael C., Mateusz Kuzak, Monther Alhamdoosh, Michelle Barker, Bérénice Batut, Mikael Borg, Salvador Capella-Gutierrez, u. a. 2017. Four Simple Recommendations to Encourage Best Practices in Research Software. <em>F1000Research</em> 6: 876. <a href="https://doi.org/10.12688/f1000research.11407.1">https://doi.org/10.12688/f1000research.11407.1</a>.</div>
|
||||
<div class="csl-left-margin">9. </div><div class="csl-right-inline">Jiménez, Rafael C., Mateusz Kuzak, Monther Alhamdoosh, Michelle Barker, Bérénice Batut, Mikael Borg, Salvador Capella-Gutierrez, u. a. 2017. Four Simple Recommendations to Encourage Best Practices in Research Software. <em>F1000Research</em> 6: 876. <a href="https://doi.org/10.12688/f1000research.11407.1">https://doi.org/10.12688/f1000research.11407.1</a>.</div>
|
||||
</div>
|
||||
<div id="ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">9. </div><div class="csl-right-inline"><em>Leitlinien zur Sicherung guter wissenschaftlicher Praxis</em>. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. <a href="https://doi.org/10.5281/zenodo.14281892">https://doi.org/10.5281/zenodo.14281892</a>.</div>
|
||||
<div class="csl-left-margin">10. </div><div class="csl-right-inline"><em>Leitlinien zur Sicherung guter wissenschaftlicher Praxis</em>. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. <a href="https://doi.org/10.5281/zenodo.14281892">https://doi.org/10.5281/zenodo.14281892</a>.</div>
|
||||
</div>
|
||||
</div></section><section class="quarto-appendix-contents" id="quarto-citation"><h2 class="anchored quarto-appendix-heading">Zitat</h2><div><div class="quarto-appendix-secondary-label">Mit BibTeX zitieren:</div><pre class="sourceCode code-with-copy quarto-appendix-bibtex"><code class="sourceCode bibtex">@online{dresselhaus2025,
|
||||
author = {Dresselhaus, Nicole and deep research, GPT-4.5},
|
||||
|
||||
@ -76,7 +76,7 @@ Dieser Anforderungskatalog richtet sich an Forschende, die keine
|
||||
Vollzeit-Programmierer sind, und soll **wissenschaftlich fundierte Richtlinien**
|
||||
für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen
|
||||
berücksichtigen Best Practices des Research Software Engineering
|
||||
[RSE](@Hasselbring2020OpenSourceResearch; @Lee2018Tensimplerules) und damit
|
||||
[@Hasselbring2020OpenSourceResearch; @Lee2018Tensimplerules] und damit
|
||||
einhergehender Prinzipien wie die des _Endings-Projekts_ für digitale
|
||||
Langlebigkeit [@EndingsPrinciples221] und
|
||||
_FAIR4RS-Prinzipien_[@BarkerEtAl2022IntroducingFAIR].
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user