diff --git a/Writing/documentation.md b/Writing/documentation.md index f9a602e..8c55ac2 100644 --- a/Writing/documentation.md +++ b/Writing/documentation.md @@ -84,7 +84,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]. diff --git a/dist/Writing/documentation.html b/dist/Writing/documentation.html index b84c97a..4112118 100644 --- a/dist/Writing/documentation.html +++ b/dist/Writing/documentation.html @@ -745,13 +745,13 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.

Einleitung

Die Dokumentation von Forschungssoftware 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 auffindbar, nachvollziehbar und wiederverwendbar zu machen.

-

Dieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll wissenschaftlich fundierte Richtlinien für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering RSE und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [1] und FAIR4RS-Prinzipien[2].

-

Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[3].

+

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 [( 1, 2] und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [3] und FAIR4RS-Prinzipien[4].

+

Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[5].

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.

Inhaltliche Anforderungen an die Dokumentation

-

Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:

+

Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[3, 6]. Insbesondere sind folgende Inhalte essenziell:

Ziel und Zweck der Software (Statement of Need)

Beschreiben Sie was die Software tut und warum sie entwickelt wurde. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die Zielgruppe (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).

Beispiel: “Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”
@@ -760,7 +760,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.

Input-/Output-Spezifikation und Datenbeschreibung

Dokumentieren Sie alle Eingabeformate, Ausgabedaten und verwendeten Datensätze. 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 Datenmodelle (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten.

-

Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [1]. 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.”
+

Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [3]. 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.”

Gerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via JSON-Schema an.

@@ -791,9 +791,9 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.

2 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.

Projekt-Metadaten (Lizenz, Zitation, Version)

-

Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[4]. Lizenzinformationen klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine LICENSE-Datei beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.

-

Zudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [5].

-

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[1].

+

Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[6]. Lizenzinformationen klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine LICENSE-Datei beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.

+

Zudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [7].

+

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[3].

Zusammenfassung der inhaltlichen Anforderungen

@@ -834,7 +834,7 @@ Zusammengefasst sollte die Dokumentation alle W-Fragen beantwor
  • 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 – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden[1].

    +

    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 – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden[3].

    Keine proprietären Formate oder Abhängigkeit von Werkzeugen

    @@ -853,7 +853,7 @@ Prinzip

    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.

    -

    Im Sinne der Digital Longevity[1] 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.

    +

    Im Sinne der Digital Longevity[3] 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.

    Strukturierte Unterteilung in weitere Dateien/Abschnitte

    @@ -1000,7 +1000,7 @@ Prinzip

    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.

    Minimaldokumentation: kurze Kommentare

    -

    Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[3] empfehlen, als ersten Schritt zumindest einen kurzen erklärenden Kommentar am Anfang jedes Scripts oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. 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 klein 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).

    +

    Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[5] empfehlen, als ersten Schritt zumindest einen kurzen erklärenden Kommentar am Anfang jedes Scripts oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. 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 klein 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).

    Verlinkte Dokumentation ist auch Dokumentation

    @@ -1016,7 +1016,7 @@ Prinzip

    Was macht eine gute Dokumentation aus

    Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS

    -

    Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[6] und den FAIR4RS-[2] bzw. ENDINGS-Prinzipien[1] steht.

    +

    Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[1] und den FAIR4RS-[4] bzw. ENDINGS-Prinzipien[3] steht.

    @@ -1076,7 +1076,7 @@ ENDINGS-Prinzipien

    Die Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge erheblich senken. Gerade Forschende, die alleine programmieren, können von (teil-)automatisierter Dokumentation 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, wann ihr Einsatz sinnvoll oder notwendig ist:

    Jupyter Notebooks und literate programming

    -

    Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [7]. 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:

    +

    Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [8]. 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.
      3. @@ -1119,7 +1119,7 @@ Prinzip

      Ab einer Codebasis > einige tausend Zeilen oder >5 nontriviale Module sollte eine generierte Dokumentation bereitstehen.

    Für umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll sein, eine Dokumentationswebsite zu generieren. Tools wie Sphinx (zusammen mit ReadTheDocs für Hosting) oder MkDocs erlauben es, aus Markdown/reStructuredText-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 Continuous Integration lassen sich diese Seiten bei jedem Git-Push automatisch aktualisieren.

    -

    Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind[1] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.

    +

    Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind[3] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.

    Solche Tools sind sinnvoll, wenn die Dokumentation sehr groß oder öffentlich weit verbreitet 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.

    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.

    Wann sollten Sie eine statische Website generieren?

    @@ -1143,7 +1143,7 @@ Prinzip

    5 kurz für: “Documentation String”

    Nutzen Sie die Möglichkeit, Dokumentation direkt im Quellcode unterzubringen, z. B. in Form von Docstrings5 (mehrzeilige Strings in Funktionen/Klassen bei Python, Roxygen-Kommentare in R, Javadoc-Kommentare in Java, etc.).

    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 jede wichtige oder von außen sichtbare Funktion, Klasse oder Modul mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.

    -

    Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. Google Style Guide für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)[8]. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa pylint, können die Verwendung erzwingen.

    +

    Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. Google Style Guide für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)[9]. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa pylint, können die Verwendung erzwingen.

    Mit Tools, wie Sphinx, Javadoc, Doxygen, MkDocs,pdoc und vielen weiteren, können aus Docstrings 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.

    @@ -1209,7 +1209,7 @@ TODO

    Fazit

    Die hier präsentierten Anforderungen und Empfehlungen bieten einen Leitfaden für die Dokumentation von Forschungssoftware in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit zu erreichen.

    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.

    -

    So schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft[9, Leitlinie 12]: 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 Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung 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: Gut dokumentierte Forschungscode ist nachhaltige Forschung.

    +

    So schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft[10, Leitlinie 12]: 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 Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung 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: Gut dokumentierte Forschungscode ist nachhaltige Forschung.

    @@ -1326,32 +1326,35 @@ TODO

    Bibliographie

    +
    +
    1.
    Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open Source Research Software. Computer 53: 84–88. https://doi.org/10.1109/MC.2020.2998235.
    +
    +
    +
    2.
    Lee, Benjamin D. 2018. Ten Simple Rules for Documenting Scientific Software. PLOS Computational Biology 14. Public Library of Science: e1006561. https://doi.org/10.1371/journal.pcbi.1006561.
    +
    -
    1.
    Endings Project Team. 2023. Endings Principles for Digital Longevity (Version 2.2.1).
    +
    3.
    Endings Project Team. 2023. Endings Principles for Digital Longevity (Version 2.2.1).
    -
    2.
    Barker, Michelle, Neil P. Chue Hong, Daniel S. Katz, Anna-Lena Lamprecht, Carlos Martinez-Ortiz, Fotis Psomopoulos, Jennifer Harrow, u. a. 2022. Introducing the FAIR Principles for Research Software. Scientific Data 9. Nature Publishing Group: 622. https://doi.org/10.1038/s41597-022-01710-x.
    +
    4.
    Barker, Michelle, Neil P. Chue Hong, Daniel S. Katz, Anna-Lena Lamprecht, Carlos Martinez-Ortiz, Fotis Psomopoulos, Jennifer Harrow, u. a. 2022. Introducing the FAIR Principles for Research Software. Scientific Data 9. Nature Publishing Group: 622. https://doi.org/10.1038/s41597-022-01710-x.
    -
    3.
    Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. PLOS Computational Biology 13. Public Library of Science: e1005510. https://doi.org/10.1371/journal.pcbi.1005510.
    +
    5.
    Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. PLOS Computational Biology 13. Public Library of Science: e1005510. https://doi.org/10.1371/journal.pcbi.1005510.
    -
    4.
    Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards FAIR Principles for Research Software. Data Science 3. SAGE Publications: 37–59. https://doi.org/10.3233/DS-190026.
    +
    6.
    Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards FAIR Principles for Research Software. Data Science 3. SAGE Publications: 37–59. https://doi.org/10.3233/DS-190026.
    -
    5.
    Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. PeerJ Computer Science 2. PeerJ Inc. https://doi.org/10.7717/peerj-cs.86.
    -
    -
    -
    6.
    Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open Source Research Software. Computer 53: 84–88. https://doi.org/10.1109/MC.2020.2998235.
    +
    7.
    Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. PeerJ Computer Science 2. PeerJ Inc. https://doi.org/10.7717/peerj-cs.86.
    -
    7.
    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. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. https://doi.org/10.3233/978-1-61499-649-1-87.
    +
    8.
    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. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. https://doi.org/10.3233/978-1-61499-649-1-87.
    -
    8.
    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. F1000Research 6: 876. https://doi.org/10.12688/f1000research.11407.1.
    +
    9.
    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. F1000Research 6: 876. https://doi.org/10.12688/f1000research.11407.1.
    -
    9.
    Leitlinien zur Sicherung guter wissenschaftlicher Praxis. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. https://doi.org/10.5281/zenodo.14281892.
    +
    10.
    Leitlinien zur Sicherung guter wissenschaftlicher Praxis. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. https://doi.org/10.5281/zenodo.14281892.

    Zitat

    Mit BibTeX zitieren:
    @online{dresselhaus2025,
   author = {Dresselhaus, Nicole and deep research, GPT-4.5},
diff --git a/dist/index.html b/dist/index.html
index a400ff8..2e5061f 100644
--- a/dist/index.html
+++ b/dist/index.html
@@ -672,7 +672,7 @@ window.Quarto = {
 
 
    
 
    
-
    
+
    
 
 
    
 
    
diff --git a/dist/index.xml b/dist/index.xml
index da79a8b..e29bcd2 100644
--- a/dist/index.xml
+++ b/dist/index.xml
@@ -23,13 +23,13 @@
 
    
 
    Einleitung
    
 
    Die Dokumentation von Forschungssoftware 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 auffindbar, nachvollziehbar und wiederverwendbar zu machen.
    
-
    Dieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll wissenschaftlich fundierte Richtlinien für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering RSE und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [1] und FAIR4RS-Prinzipien[2].
    
-
    Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[3].
    
+
    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 [( 1, 2] und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [3] und FAIR4RS-Prinzipien[4].
    
+
    Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[5].
    
 
    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.
    
 
    
 
    
 
    Inhaltliche Anforderungen an die Dokumentation
    
-
    Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:
    
+
    Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[3, 6]. Insbesondere sind folgende Inhalte essenziell:
    
 
    
 
    Ziel und Zweck der Software (Statement of Need)
    
 
    Beschreiben Sie was die Software tut und warum sie entwickelt wurde. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die Zielgruppe (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.  Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).
    Beispiel: “Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”
    
@@ -38,7 +38,7 @@
 
    Input-/Output-Spezifikation und Datenbeschreibung
    
 
    Dokumentieren Sie alle Eingabeformate, Ausgabedaten und verwendeten Datensätze. 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 Datenmodelle (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten.
    
-
    Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [1]. 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.”
    
+
    Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [3]. 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.”
    
 
    Gerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via JSON-Schema an.
    
 
    
 
    
@@ -69,9 +69,9 @@
 
    2 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.
    
 
    
 
    Projekt-Metadaten (Lizenz, Zitation, Version)
    
-
    Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[4]. Lizenzinformationen klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine LICENSE-Datei beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.
    
-
    Zudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [5].
    
-
    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[1].
    
+
    Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[6]. Lizenzinformationen klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine LICENSE-Datei beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.
    
+
    Zudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [7].
    
+
    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[3].
    
 
    
 
    
 
    Zusammenfassung der inhaltlichen Anforderungen
    
@@ -112,7 +112,7 @@ Zusammengefasst sollte die Dokumentation alle W-Fragen beantwor
 
  • 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 – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden[1].
    
+
    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 – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden[3].
    
 
    
 
    
 
    Keine proprietären Formate oder Abhängigkeit von Werkzeugen
    
@@ -131,7 +131,7 @@ Prinzip
 
    
 
    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.
    
-
    Im Sinne der Digital Longevity[1] 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.
    
+
    Im Sinne der Digital Longevity[3] 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.

    Strukturierte Unterteilung in weitere Dateien/Abschnitte

    @@ -278,7 +278,7 @@ Prinzip

    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.

    Minimaldokumentation: kurze Kommentare

    -

    Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[3] empfehlen, als ersten Schritt zumindest einen kurzen erklärenden Kommentar am Anfang jedes Scripts oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. 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 klein 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).

    +

    Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[5] empfehlen, als ersten Schritt zumindest einen kurzen erklärenden Kommentar am Anfang jedes Scripts oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. 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 klein 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).

    Verlinkte Dokumentation ist auch Dokumentation

    @@ -294,7 +294,7 @@ Prinzip

    Was macht eine gute Dokumentation aus

    Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS

    -

    Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[6] und den FAIR4RS-[2] bzw. ENDINGS-Prinzipien[1] steht.

    +

    Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[1] und den FAIR4RS-[4] bzw. ENDINGS-Prinzipien[3] steht.

    @@ -354,7 +354,7 @@ ENDINGS-Prinzipien

    Die Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge erheblich senken. Gerade Forschende, die alleine programmieren, können von (teil-)automatisierter Dokumentation 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, wann ihr Einsatz sinnvoll oder notwendig ist:

    Jupyter Notebooks und literate programming

    -

    Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [7]. 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:

    +

    Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [8]. 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.
      3. @@ -397,7 +397,7 @@ Prinzip

      Ab einer Codebasis > einige tausend Zeilen oder >5 nontriviale Module sollte eine generierte Dokumentation bereitstehen.

    Für umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll sein, eine Dokumentationswebsite zu generieren. Tools wie Sphinx (zusammen mit ReadTheDocs für Hosting) oder MkDocs erlauben es, aus Markdown/reStructuredText-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 Continuous Integration lassen sich diese Seiten bei jedem Git-Push automatisch aktualisieren.

    -

    Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind[1] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.

    +

    Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind[3] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.

    Solche Tools sind sinnvoll, wenn die Dokumentation sehr groß oder öffentlich weit verbreitet 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.

    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.

    Wann sollten Sie eine statische Website generieren?

    @@ -421,7 +421,7 @@ Prinzip

    5 kurz für: “Documentation String”

    Nutzen Sie die Möglichkeit, Dokumentation direkt im Quellcode unterzubringen, z. B. in Form von Docstrings5 (mehrzeilige Strings in Funktionen/Klassen bei Python, Roxygen-Kommentare in R, Javadoc-Kommentare in Java, etc.).

    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 jede wichtige oder von außen sichtbare Funktion, Klasse oder Modul mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.

    -

    Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. Google Style Guide für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)[8]. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa pylint, können die Verwendung erzwingen.

    +

    Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. Google Style Guide für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)[9]. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa pylint, können die Verwendung erzwingen.

    Mit Tools, wie Sphinx, Javadoc, Doxygen, MkDocs,pdoc und vielen weiteren, können aus Docstrings 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.

    @@ -487,7 +487,7 @@ TODO

    Fazit

    Die hier präsentierten Anforderungen und Empfehlungen bieten einen Leitfaden für die Dokumentation von Forschungssoftware in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit zu erreichen.

    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.

    -

    So schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft[9, Leitlinie 12]: 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 Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung 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: Gut dokumentierte Forschungscode ist nachhaltige Forschung.

    +

    So schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft[10, Leitlinie 12]: 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 Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung 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: Gut dokumentierte Forschungscode ist nachhaltige Forschung.

    @@ -604,32 +604,35 @@ TODO

    Bibliographie

    +
    +
    1.
    Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open Source Research Software. Computer 53: 84–88. https://doi.org/10.1109/MC.2020.2998235.
    +
    +
    +
    2.
    Lee, Benjamin D. 2018. Ten Simple Rules for Documenting Scientific Software. PLOS Computational Biology 14. Public Library of Science: e1006561. https://doi.org/10.1371/journal.pcbi.1006561.
    +
    -
    1.
    Endings Project Team. 2023. Endings Principles for Digital Longevity (Version 2.2.1).
    +
    3.
    Endings Project Team. 2023. Endings Principles for Digital Longevity (Version 2.2.1).
    -
    2.
    Barker, Michelle, Neil P. Chue Hong, Daniel S. Katz, Anna-Lena Lamprecht, Carlos Martinez-Ortiz, Fotis Psomopoulos, Jennifer Harrow, u. a. 2022. Introducing the FAIR Principles for Research Software. Scientific Data 9. Nature Publishing Group: 622. https://doi.org/10.1038/s41597-022-01710-x.
    +
    4.
    Barker, Michelle, Neil P. Chue Hong, Daniel S. Katz, Anna-Lena Lamprecht, Carlos Martinez-Ortiz, Fotis Psomopoulos, Jennifer Harrow, u. a. 2022. Introducing the FAIR Principles for Research Software. Scientific Data 9. Nature Publishing Group: 622. https://doi.org/10.1038/s41597-022-01710-x.
    -
    3.
    Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. PLOS Computational Biology 13. Public Library of Science: e1005510. https://doi.org/10.1371/journal.pcbi.1005510.
    +
    5.
    Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. PLOS Computational Biology 13. Public Library of Science: e1005510. https://doi.org/10.1371/journal.pcbi.1005510.
    -
    4.
    Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards FAIR Principles for Research Software. Data Science 3. SAGE Publications: 37–59. https://doi.org/10.3233/DS-190026.
    +
    6.
    Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards FAIR Principles for Research Software. Data Science 3. SAGE Publications: 37–59. https://doi.org/10.3233/DS-190026.
    -
    5.
    Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. PeerJ Computer Science 2. PeerJ Inc. https://doi.org/10.7717/peerj-cs.86.
    -
    -
    -
    6.
    Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open Source Research Software. Computer 53: 84–88. https://doi.org/10.1109/MC.2020.2998235.
    +
    7.
    Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. PeerJ Computer Science 2. PeerJ Inc. https://doi.org/10.7717/peerj-cs.86.
    -
    7.
    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. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. https://doi.org/10.3233/978-1-61499-649-1-87.
    +
    8.
    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. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. https://doi.org/10.3233/978-1-61499-649-1-87.
    -
    8.
    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. F1000Research 6: 876. https://doi.org/10.12688/f1000research.11407.1.
    +
    9.
    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. F1000Research 6: 876. https://doi.org/10.12688/f1000research.11407.1.
    -
    9.
    Leitlinien zur Sicherung guter wissenschaftlicher Praxis. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. https://doi.org/10.5281/zenodo.14281892.
    +
    10.
    Leitlinien zur Sicherung guter wissenschaftlicher Praxis. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. https://doi.org/10.5281/zenodo.14281892.

    Zitat

    Mit BibTeX zitieren:
    @online{dresselhaus2025,
   author = {Dresselhaus, Nicole and deep research, GPT-4.5},
diff --git a/dist/search.json b/dist/search.json
index ddd6398..3000310 100644
--- a/dist/search.json
+++ b/dist/search.json
@@ -1146,7 +1146,7 @@
     "href": "Writing/documentation.html",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "",
-    "text": "Die Dokumentation von Forschungssoftware 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 auffindbar, nachvollziehbar und wiederverwendbar zu machen.\nDieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll wissenschaftlich fundierte Richtlinien für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering RSE und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [1] und FAIR4RS-Prinzipien[2].\nZiel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[3].\nIm 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.",
+    "text": "Die Dokumentation von Forschungssoftware 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 auffindbar, nachvollziehbar und wiederverwendbar zu machen.\nDieser 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 [( 1, 2] und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [3] und FAIR4RS-Prinzipien[4].\nZiel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[5].\nIm 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.",
     "crumbs": [
       "Home",
       "Serious",
@@ -1159,7 +1159,7 @@
     "href": "Writing/documentation.html#einleitung",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "",
-    "text": "Die Dokumentation von Forschungssoftware 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 auffindbar, nachvollziehbar und wiederverwendbar zu machen.\nDieser Anforderungskatalog richtet sich an Forschende, die keine Vollzeit-Programmierer sind, und soll wissenschaftlich fundierte Richtlinien für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen berücksichtigen Best Practices des Research Software Engineering RSE und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [1] und FAIR4RS-Prinzipien[2].\nZiel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[3].\nIm 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.",
+    "text": "Die Dokumentation von Forschungssoftware 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 auffindbar, nachvollziehbar und wiederverwendbar zu machen.\nDieser 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 [( 1, 2] und damit einhergehender Prinzipien wie die des Endings-Projekts für digitale Langlebigkeit [3] und FAIR4RS-Prinzipien[4].\nZiel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die Nachvollziehbarkeit der Ergebnisse als auch eine Weiterverwendung der Software zu ermöglichen[5].\nIm 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.",
     "crumbs": [
       "Home",
       "Serious",
@@ -1172,7 +1172,7 @@
     "href": "Writing/documentation.html#inhaltliche-anforderungen-an-die-dokumentation",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "Inhaltliche Anforderungen an die Dokumentation",
-    "text": "Inhaltliche Anforderungen an die Dokumentation\nEin zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:\n\nZiel und Zweck der Software (Statement of Need)\nBeschreiben Sie was die Software tut und warum sie entwickelt wurde. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die Zielgruppe (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.  Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).Beispiel: “Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”\n\n\nInput-/Output-Spezifikation und Datenbeschreibung\nDokumentieren Sie alle Eingabeformate, Ausgabedaten und verwendeten Datensätze. 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.\nFalls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies umfasst die Datenmodelle (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten.\nGemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [1]. 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.”\nGerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via JSON-Schema an.\n\n\nCode-Abhängigkeiten und technische Voraussetzungen\nListen Sie alle Abhängigkeiten (Dependencies) der Software auf. Dazu gehören verwendete Programmiersprachen/Versionen, erforderliche Bibliotheken oder Frameworks, und sonstige Systemvoraussetzungen (z. B. Betriebssystem, Mindesthardware, Datenbank-Versionen). Wichtig ist, wie diese Abhängigkeiten installiert werden können. Optimal ist eine automatisierte Installationsroutine (z. B. ein requirements.txt für Python oder ein Paketmanager-Befehl). In jedem Fall sollte die Dokumentation mindestens Schritt-für-Schritt-Installationsanleitungen enthalten (inklusive evtl. benötigter Vorkenntnisse, z. B. “Python 3 erforderlich”). Beispiel: “Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation: pip install -r requirements.txt.” Falls spezielle technische Voraussetzungen bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder große Speicherkapazitäten – sind diese zu nennen.\n\n\nWissenschaftlicher Hintergrund und theoretischer Kontext\nDa es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext 1 offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.\n1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können.  Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”\nWichtig ist, dass die Dokumentation den Brückenschlag zwischen Code und Forschung herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.\n\n\nBekannte Limitationen, Annahmen und Fehlermeldungen\nGeben Sie ehrlich Auskunft über die Grenzen der Software:\n\nWelche Fälle werden nicht abgedeckt?\nWelche Annahmen über die Daten oder Anwendungsszenarien werden getroffen?\n\n Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.Beispielsweise: “funktioniert nur für Deutschsprachige Texte” oder “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”\nFalls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.\nAuch aussagekräftige Fehlermeldungen im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann.  Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.Beispiel: “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”\n\n\nWeiterentwicklung und Beitragsmöglichkeiten\nObwohl viele Digital-Humanities-Tools primär von Einzelpersonen genutzt werden, sollte dennoch angegeben werden, wie andere ggf. zur Software beitragen oder Support erhalten können. Ein kurzer Hinweis auf den Issue-Tracker (z. B. “Fehler bitte über GitHub-Issues melden”) oder auf die Kontaktmöglichkeit zum*zur Autor*in (E-Mail) gehört dazu.\nEbenso können Community Guidelines skizziert werden: etwa Code-Standards oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte reicht oft ein Satz wie “Beiträge durch Pull Requests sind willkommen; bei Fragen wenden Sie sich an…”. 2\n2 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.\n\nProjekt-Metadaten (Lizenz, Zitation, Version)\nTeil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[4]. Lizenzinformationen klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine LICENSE-Datei beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.\nZudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [5].\nSchließ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[1].\n\n\nZusammenfassung der inhaltlichen Anforderungen\n\n\n\n\n\n\nZusammengefasst sollte die Dokumentation alle W-Fragen beantworten\n\n\n\n\nWas tut die Software,\nwarum wurde sie geschrieben (wissenschaftlicher Zweck),\nwer soll sie nutzen,\nwie wird sie benutzt (Inputs, Outputs, Abläufe),\nwomit läuft sie (Umgebung/Abhängigkeiten),\nunter welchen Bedingungen (Annahmen/Limitationen) und\nwohin können sich Nutzer wenden (Support/Zitation).\n\n\n\nAll diese Punkte sorgen für Nachvollziehbarkeit (im Sinne von Reproduzierbarkeit der Ergebnisse) und Weiterverwendbarkeit (im Sinne von Adaptierbarkeit der Software für neue Kontexte).",
+    "text": "Inhaltliche Anforderungen an die Dokumentation\nEin zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[3, 6]. Insbesondere sind folgende Inhalte essenziell:\n\nZiel und Zweck der Software (Statement of Need)\nBeschreiben Sie was die Software tut und warum sie entwickelt wurde. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die Zielgruppe (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.  Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).Beispiel: “Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”\n\n\nInput-/Output-Spezifikation und Datenbeschreibung\nDokumentieren Sie alle Eingabeformate, Ausgabedaten und verwendeten Datensätze. 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.\nFalls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies umfasst die Datenmodelle (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten.\nGemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [3]. 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.”\nGerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via JSON-Schema an.\n\n\nCode-Abhängigkeiten und technische Voraussetzungen\nListen Sie alle Abhängigkeiten (Dependencies) der Software auf. Dazu gehören verwendete Programmiersprachen/Versionen, erforderliche Bibliotheken oder Frameworks, und sonstige Systemvoraussetzungen (z. B. Betriebssystem, Mindesthardware, Datenbank-Versionen). Wichtig ist, wie diese Abhängigkeiten installiert werden können. Optimal ist eine automatisierte Installationsroutine (z. B. ein requirements.txt für Python oder ein Paketmanager-Befehl). In jedem Fall sollte die Dokumentation mindestens Schritt-für-Schritt-Installationsanleitungen enthalten (inklusive evtl. benötigter Vorkenntnisse, z. B. “Python 3 erforderlich”). Beispiel: “Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation: pip install -r requirements.txt.” Falls spezielle technische Voraussetzungen bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder große Speicherkapazitäten – sind diese zu nennen.\n\n\nWissenschaftlicher Hintergrund und theoretischer Kontext\nDa es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext 1 offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.\n1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können.  Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”\nWichtig ist, dass die Dokumentation den Brückenschlag zwischen Code und Forschung herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.\n\n\nBekannte Limitationen, Annahmen und Fehlermeldungen\nGeben Sie ehrlich Auskunft über die Grenzen der Software:\n\nWelche Fälle werden nicht abgedeckt?\nWelche Annahmen über die Daten oder Anwendungsszenarien werden getroffen?\n\n Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.Beispielsweise: “funktioniert nur für Deutschsprachige Texte” oder “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”\nFalls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.\nAuch aussagekräftige Fehlermeldungen im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann.  Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.Beispiel: “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”\n\n\nWeiterentwicklung und Beitragsmöglichkeiten\nObwohl viele Digital-Humanities-Tools primär von Einzelpersonen genutzt werden, sollte dennoch angegeben werden, wie andere ggf. zur Software beitragen oder Support erhalten können. Ein kurzer Hinweis auf den Issue-Tracker (z. B. “Fehler bitte über GitHub-Issues melden”) oder auf die Kontaktmöglichkeit zum*zur Autor*in (E-Mail) gehört dazu.\nEbenso können Community Guidelines skizziert werden: etwa Code-Standards oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte reicht oft ein Satz wie “Beiträge durch Pull Requests sind willkommen; bei Fragen wenden Sie sich an…”. 2\n2 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.\n\nProjekt-Metadaten (Lizenz, Zitation, Version)\nTeil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[6]. Lizenzinformationen klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine LICENSE-Datei beizulegen, aber auch in der README kurz zu erwähnen, unter welcher Lizenz die Software steht. Für Forschungssoftware empfiehlt sich eine offene Lizenz (z. B. MIT, BSD oder Apache 2.0 für Code, CC-BY für Daten), um Nachnutzung nicht zu behindern.\nZudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [7].\nSchließ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[3].\n\n\nZusammenfassung der inhaltlichen Anforderungen\n\n\n\n\n\n\nZusammengefasst sollte die Dokumentation alle W-Fragen beantworten\n\n\n\n\nWas tut die Software,\nwarum wurde sie geschrieben (wissenschaftlicher Zweck),\nwer soll sie nutzen,\nwie wird sie benutzt (Inputs, Outputs, Abläufe),\nwomit läuft sie (Umgebung/Abhängigkeiten),\nunter welchen Bedingungen (Annahmen/Limitationen) und\nwohin können sich Nutzer wenden (Support/Zitation).\n\n\n\nAll diese Punkte sorgen für Nachvollziehbarkeit (im Sinne von Reproduzierbarkeit der Ergebnisse) und Weiterverwendbarkeit (im Sinne von Adaptierbarkeit der Software für neue Kontexte).",
     "crumbs": [
       "Home",
       "Serious",
@@ -1185,7 +1185,7 @@
     "href": "Writing/documentation.html#format-und-struktur-der-dokumentation",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "Format und Struktur der Dokumentation",
-    "text": "Format und Struktur der Dokumentation\nFür Forschende ohne viel Ressourcen muss die Dokumentation einfach zugänglich, leicht pflegbar und ohne Spezialsoftware erstellbar sein.\n\nREADME.md als zentrales Dokument\nDie 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:\n\nZweck der Software,\nKurzbeschreibung,\nInstallation,\nkurzer Nutzungsbeispiel,\nKontakt/Lizenz.\n\nAuf 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 – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden[1].\n\n\nKeine proprietären Formate oder Abhängigkeit von Werkzeugen\n\n\n\n\n\n\n\nPrinzip\n\n\n\nDokumentation gehört zum Code und muss auch ohne Programm lesbar sein.\n\nUm Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown, reStructuredText).\nVermeiden 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.\nIm Sinne der Digital Longevity[1] 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.\n\n\nStrukturierte Unterteilung in weitere Dateien/Abschnitte\n\n\nexample-project/\n├── README.md\n├── CONTRIBUTING.md (optional)\n├── CHANGELOG.md    (optional)\n├── CITATION.md     (oder CITATION.cff)\n├── LICENSE\n├── data/           (optional)\n│   └── sample_data.csv\n├── docs/           (optional)\n│   ├── INSTALL.md\n│   └── USAGE.md\n├── examples/       (optional)\n│   └── example_workflow.ipynb\n└── src/\n    ├── script.py\n    └── module/\n        └── helper.py\nBeispielhafter Struktur eines Code-Repositories\nSollte 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 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.:\n\nREADME.md – Überblick (Ziel, Installation, kurzes Beispiel, Lizenz/Zitation)\ndocs/ Verzeichnis mit weiteren .md-Dateien für tiefergehende Dokumentation (optional)\nCONTRIBUTING.md – Hinweise für Beiträger (falls relevant)\nLICENSE – Lizenztext\nCITATION.cff oder CITATION.md – wie zu zitieren.\n\nDiese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie leicht auffindbar und ggf. direkt durch Tools verarbeitbar sind.\n\n\nÜbersichtlichkeit und Navigierbarkeit\n\n\n\n\n\n\n\nPrinzip\n\n\n\n“Don’t Repeat Yourself”: Alle Informationen zu einem Thema (Installation/Nutzung/…) an derselben Stelle sammeln und keinesfalls mehrfach pflegen.\n\nStrukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit Leser schnell die gesuchten Informationen finden. Eine logische Gliederung 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.\nAchten 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.\n\n\nBeispiele, Codeblöcke und ggf. Abbildungen einbinden\n\n\n\n\n\n\n\nPrinzip\n\n\n\nZeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.\n\nNutzen 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.).\nAchten 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 werden3.\n3 zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder graphvizDiese 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.\n\n\n\n\n\n\nTypische Nutzungsszenarien und Workflows\n\n\n\n\n\nZeigen Sie anhand von konkreten Beispielen, wie die Software benutzt wird. Ein Quickstart-Beispiel senkt die Einstiegshürde enorm. Dies kann z. B. eine Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum gewünschten Ergebnis kommt.\nBeschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf. können mehrere Anwendungsfälle skizziert werden (z. B. “Analyse eines einzelnen Briefes” vs. “Batch-Verarbeitung eines gesamten Korpus”).\nDiese Beispiele sollten realistisch und möglichst repräsentativ für wissenschaftliche Anwendungen sein. Nutzen Sie gerne kleine, mitgelieferte Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei Kommandozeilentools, via --help dokumentiert).\n\n\n\n\n\nUmfang und Fokus der Dokumentation\n\n\n\n\n\n\n\nPrinzip\n\n\n\nKann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?\n\nWenn ja, ist der Detailgrad angemessen\nWenn die Person hingegen nach 10 Seiten oder mehr als 1 Stunde immer noch nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.\n\n\nEin effizienter Umfang lässt sich erreichen, indem sie alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles andere skippen.\n\nNegativbeispiele umfassen:\n\njeder interne Programmiertrick wird erläutert – Quellcode-Kommentare richten sich an Entwickler*innen, während die Nutzendendokumentation sich auf Nutzung und Kontext beschränkt\nseitenlange Theorieabhandlungen (verweisen Sie stattdessen auf Papers)\ngenerische Erklärungen bekannter Technologien (man muss Git oder Python nicht in der Doku erklären, sondern kann referenzieren)\n\n\nHalten Sie auch die Sprache prägnant:\n\nkurze Absätze\nListen\nund einfache Sätze\n\nerhöhen die Lesbarkeit.\nFachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht kennen.\n\nFokus auf Nutzer*innen - nicht Entwickler*innen\nStellen Sie sich beim Schreiben der Doku die verschiedenen Nutzerrollen vor: “Zukünftiges Ich”, Kolleg*innen, Fachforscher*innen anderer Disziplin und ggf. Software-Entwickler*innen, die den Code erweitern. Jede dieser Gruppen möchte bestimmte Dinge wissen.\nForschende fragen:\n\nWas kann das Tool?\nWie benutze ich es?\nIn welchem Kontext steht es?\n\nEntwicklende Personen fragen:\n\nWie kann ich beitragen?\nWie funktioniert es unter der Haube?\n\nPriorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse. Konzentrieren Sie die Hauptdokumentation darauf, das Nutzen und Verstehen der Software von außen zu ermöglichen.\n\n\n\nPriorisierung bei Zeitmangel\nDieser 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.\n\nMinimaldokumentation: kurze Kommentare\nBeginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[3] empfehlen, als ersten Schritt zumindest einen kurzen erklärenden Kommentar am Anfang jedes Scripts oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. 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 klein 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).\n\n\nVerlinkte Dokumentation ist auch Dokumentation\nNutzen Sie Verweise und vorhandene Ressourcen. Wenn z. B. Ihr Tool auf einem komplizierten Setup (Datenbank, Webserver) aufbaut, brauchen Sie nicht jede Installationsoption im Detail in Ihrer Doku zu reproduzieren – verlinken Sie auf offizielle Installationsanleitungen dieser Abhängigkeiten, und nennen Sie nur Ihre spezifischen Konfigurationen und verlinken sie auf die Dokumentation des Setup-Elementes für alles weitere. Ebenso können Tutorials oder Papers, die schon existieren, als weiterführende Links angegeben werden, anstatt Inhalte redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.\n\n\nUnd anschließend?\nWenn der Zeitmangel vorüber ist4, sollte man nach und nach das folgende Kapitel umsetzen.\n4 als ob DAS je der Fall wäre -.-",
+    "text": "Format und Struktur der Dokumentation\nFür Forschende ohne viel Ressourcen muss die Dokumentation einfach zugänglich, leicht pflegbar und ohne Spezialsoftware erstellbar sein.\n\nREADME.md als zentrales Dokument\nDie 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:\n\nZweck der Software,\nKurzbeschreibung,\nInstallation,\nkurzer Nutzungsbeispiel,\nKontakt/Lizenz.\n\nAuf 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 – denn Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden[3].\n\n\nKeine proprietären Formate oder Abhängigkeit von Werkzeugen\n\n\n\n\n\n\n\nPrinzip\n\n\n\nDokumentation gehört zum Code und muss auch ohne Programm lesbar sein.\n\nUm Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown, reStructuredText).\nVermeiden 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.\nIm Sinne der Digital Longevity[3] 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.\n\n\nStrukturierte Unterteilung in weitere Dateien/Abschnitte\n\n\nexample-project/\n├── README.md\n├── CONTRIBUTING.md (optional)\n├── CHANGELOG.md    (optional)\n├── CITATION.md     (oder CITATION.cff)\n├── LICENSE\n├── data/           (optional)\n│   └── sample_data.csv\n├── docs/           (optional)\n│   ├── INSTALL.md\n│   └── USAGE.md\n├── examples/       (optional)\n│   └── example_workflow.ipynb\n└── src/\n    ├── script.py\n    └── module/\n        └── helper.py\nBeispielhafter Struktur eines Code-Repositories\nSollte 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 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.:\n\nREADME.md – Überblick (Ziel, Installation, kurzes Beispiel, Lizenz/Zitation)\ndocs/ Verzeichnis mit weiteren .md-Dateien für tiefergehende Dokumentation (optional)\nCONTRIBUTING.md – Hinweise für Beiträger (falls relevant)\nLICENSE – Lizenztext\nCITATION.cff oder CITATION.md – wie zu zitieren.\n\nDiese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie leicht auffindbar und ggf. direkt durch Tools verarbeitbar sind.\n\n\nÜbersichtlichkeit und Navigierbarkeit\n\n\n\n\n\n\n\nPrinzip\n\n\n\n“Don’t Repeat Yourself”: Alle Informationen zu einem Thema (Installation/Nutzung/…) an derselben Stelle sammeln und keinesfalls mehrfach pflegen.\n\nStrukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit Leser schnell die gesuchten Informationen finden. Eine logische Gliederung 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.\nAchten 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.\n\n\nBeispiele, Codeblöcke und ggf. Abbildungen einbinden\n\n\n\n\n\n\n\nPrinzip\n\n\n\nZeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.\n\nNutzen 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.).\nAchten 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 werden3.\n3 zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder graphvizDiese 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.\n\n\n\n\n\n\nTypische Nutzungsszenarien und Workflows\n\n\n\n\n\nZeigen Sie anhand von konkreten Beispielen, wie die Software benutzt wird. Ein Quickstart-Beispiel senkt die Einstiegshürde enorm. Dies kann z. B. eine Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum gewünschten Ergebnis kommt.\nBeschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf. können mehrere Anwendungsfälle skizziert werden (z. B. “Analyse eines einzelnen Briefes” vs. “Batch-Verarbeitung eines gesamten Korpus”).\nDiese Beispiele sollten realistisch und möglichst repräsentativ für wissenschaftliche Anwendungen sein. Nutzen Sie gerne kleine, mitgelieferte Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei Kommandozeilentools, via --help dokumentiert).\n\n\n\n\n\nUmfang und Fokus der Dokumentation\n\n\n\n\n\n\n\nPrinzip\n\n\n\nKann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?\n\nWenn ja, ist der Detailgrad angemessen\nWenn die Person hingegen nach 10 Seiten oder mehr als 1 Stunde immer noch nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.\n\n\nEin effizienter Umfang lässt sich erreichen, indem sie alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles andere skippen.\n\nNegativbeispiele umfassen:\n\njeder interne Programmiertrick wird erläutert – Quellcode-Kommentare richten sich an Entwickler*innen, während die Nutzendendokumentation sich auf Nutzung und Kontext beschränkt\nseitenlange Theorieabhandlungen (verweisen Sie stattdessen auf Papers)\ngenerische Erklärungen bekannter Technologien (man muss Git oder Python nicht in der Doku erklären, sondern kann referenzieren)\n\n\nHalten Sie auch die Sprache prägnant:\n\nkurze Absätze\nListen\nund einfache Sätze\n\nerhöhen die Lesbarkeit.\nFachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht kennen.\n\nFokus auf Nutzer*innen - nicht Entwickler*innen\nStellen Sie sich beim Schreiben der Doku die verschiedenen Nutzerrollen vor: “Zukünftiges Ich”, Kolleg*innen, Fachforscher*innen anderer Disziplin und ggf. Software-Entwickler*innen, die den Code erweitern. Jede dieser Gruppen möchte bestimmte Dinge wissen.\nForschende fragen:\n\nWas kann das Tool?\nWie benutze ich es?\nIn welchem Kontext steht es?\n\nEntwicklende Personen fragen:\n\nWie kann ich beitragen?\nWie funktioniert es unter der Haube?\n\nPriorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse. Konzentrieren Sie die Hauptdokumentation darauf, das Nutzen und Verstehen der Software von außen zu ermöglichen.\n\n\n\nPriorisierung bei Zeitmangel\nDieser 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.\n\nMinimaldokumentation: kurze Kommentare\nBeginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[5] empfehlen, als ersten Schritt zumindest einen kurzen erklärenden Kommentar am Anfang jedes Scripts oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. 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 klein 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).\n\n\nVerlinkte Dokumentation ist auch Dokumentation\nNutzen Sie Verweise und vorhandene Ressourcen. Wenn z. B. Ihr Tool auf einem komplizierten Setup (Datenbank, Webserver) aufbaut, brauchen Sie nicht jede Installationsoption im Detail in Ihrer Doku zu reproduzieren – verlinken Sie auf offizielle Installationsanleitungen dieser Abhängigkeiten, und nennen Sie nur Ihre spezifischen Konfigurationen und verlinken sie auf die Dokumentation des Setup-Elementes für alles weitere. Ebenso können Tutorials oder Papers, die schon existieren, als weiterführende Links angegeben werden, anstatt Inhalte redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.\n\n\nUnd anschließend?\nWenn der Zeitmangel vorüber ist4, sollte man nach und nach das folgende Kapitel umsetzen.\n4 als ob DAS je der Fall wäre -.-",
     "crumbs": [
       "Home",
       "Serious",
@@ -1198,7 +1198,7 @@
     "href": "Writing/documentation.html#was-macht-eine-gute-dokumentation-aus",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "Was macht eine gute Dokumentation aus",
-    "text": "Was macht eine gute Dokumentation aus\n\nFormelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS\nBeachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[6] und den FAIR4RS-[2] bzw. ENDINGS-Prinzipien[1] steht.\n\n\n\n\n\n\n\nFAIR4RS-Prinzipien für Software\n\n\n\nDie FAIR4RS-Prinzipien sind eine Anpassung der Ursprünglich nur für Daten gedachten FAIR-Prinzipien. Der Fokus liegt hier nicht auf Software selbst, sondern auf eine Nutzung von Software die ein Äquivalent zur Nutzung von FAIR-Daten darstellt.\n\n\n\n\n\n\n\nENDINGS-Prinzipien\n\n\n\nDie ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit.\n\n\nGute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von\n\nReproduzierbarkeit (Installation, Daten, Beispiele),\nOffenheit (Lizenz, offene Formate) und\nNachhaltigkeit (Versionierung, Langlebigkeit der Doku).\n\nIndem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche Softwarepraxis.\n\n\nNutzungshilfen außerhalb der Dokumentation\nFalls Ihre Software ein Command-Line Interface (CLI) hat, stellen Sie sicher, dass eine eingebaute Hilfe vorhanden ist (z. B. Ausgabe bei --help). Viele Nutzer greifen zunächst darauf zurück. Dieses Hilfemenü sollte kurz erläutern, welche Subkommandos oder Optionen existieren. Moderne CLI-Frameworks generieren solche Hilfen oft automatisch aus Ihrem Code (z. B. argparse in Python erzeugen --help-Texte). Nutzen Sie das, um konsistente Infos zu garantieren.\nFür GUI-Anwendungen sollten Tooltips, Hilfetexte in der Oberfläche oder zumindest ein kleiner Help-Abschnitt im Handbuch vorhanden sein. Diese eingebetteten Hilfen ersetzen keine ausführliche Dokumentation, aber sie senken die Schwelle für alltägliche Fragen.\n\n\nKontinuierliche Verbesserung und Feedback\nDokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:\n\nfrüh Feedback von Testnutzer*innen oder Kolleg*innen einzuholen: Lassen Sie jemanden die Anleitung befolgen und hören Sie auf Stolpersteine. Oft zeigen sich Lücken erst im Praxistest (“Ich wusste nicht, was ich nach Schritt X tun soll” etc.).\nPlanen Sie Zeiten ein, die Dokumentation nachzuführen, insbesondere wenn sich die Software ändert. Ein lebendiges Projekt wird vielleicht Release für Release die Dokumentation erweitern (evtl. neue Tutorials, neue Module dokumentieren). Spätestens zum Release-Zeitpunkt sollten diese auffallen und ggf. als Issues adressiert werden.\nNutzen Sie auch Issues für Dokumentation: Wenn Nutzer Fragen stellen, überlegen Sie, ob die Antwort in die offizielle Doku übernommen werden sollte. So wächst die Dokumentation organisch entlang der tatsächlichen Bedürfnisse.\n\n\n\nPositiv- und Negativbeispiele studieren\nSchlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf Projekte mit exzellenter Doku. Im Journal of Open Source Software (JOSS) werden z.B. Softwareartikel veröffentlicht, bei denen die zugehörigen Repositorien aufgrund des Review-Prozesses vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.\nNutzen Sie solche Ressourcen; sie ersparen einem das Rad neu zu erfinden. Allerdings: Adaptieren Sie sie auf Ihre Bedürfnisse – nicht jede Vorlage passt 1:1.",
+    "text": "Was macht eine gute Dokumentation aus\n\nFormelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS\nBeachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[1] und den FAIR4RS-[4] bzw. ENDINGS-Prinzipien[3] steht.\n\n\n\n\n\n\n\nFAIR4RS-Prinzipien für Software\n\n\n\nDie FAIR4RS-Prinzipien sind eine Anpassung der Ursprünglich nur für Daten gedachten FAIR-Prinzipien. Der Fokus liegt hier nicht auf Software selbst, sondern auf eine Nutzung von Software die ein Äquivalent zur Nutzung von FAIR-Daten darstellt.\n\n\n\n\n\n\n\nENDINGS-Prinzipien\n\n\n\nDie ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit.\n\n\nGute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von\n\nReproduzierbarkeit (Installation, Daten, Beispiele),\nOffenheit (Lizenz, offene Formate) und\nNachhaltigkeit (Versionierung, Langlebigkeit der Doku).\n\nIndem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche Softwarepraxis.\n\n\nNutzungshilfen außerhalb der Dokumentation\nFalls Ihre Software ein Command-Line Interface (CLI) hat, stellen Sie sicher, dass eine eingebaute Hilfe vorhanden ist (z. B. Ausgabe bei --help). Viele Nutzer greifen zunächst darauf zurück. Dieses Hilfemenü sollte kurz erläutern, welche Subkommandos oder Optionen existieren. Moderne CLI-Frameworks generieren solche Hilfen oft automatisch aus Ihrem Code (z. B. argparse in Python erzeugen --help-Texte). Nutzen Sie das, um konsistente Infos zu garantieren.\nFür GUI-Anwendungen sollten Tooltips, Hilfetexte in der Oberfläche oder zumindest ein kleiner Help-Abschnitt im Handbuch vorhanden sein. Diese eingebetteten Hilfen ersetzen keine ausführliche Dokumentation, aber sie senken die Schwelle für alltägliche Fragen.\n\n\nKontinuierliche Verbesserung und Feedback\nDokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:\n\nfrüh Feedback von Testnutzer*innen oder Kolleg*innen einzuholen: Lassen Sie jemanden die Anleitung befolgen und hören Sie auf Stolpersteine. Oft zeigen sich Lücken erst im Praxistest (“Ich wusste nicht, was ich nach Schritt X tun soll” etc.).\nPlanen Sie Zeiten ein, die Dokumentation nachzuführen, insbesondere wenn sich die Software ändert. Ein lebendiges Projekt wird vielleicht Release für Release die Dokumentation erweitern (evtl. neue Tutorials, neue Module dokumentieren). Spätestens zum Release-Zeitpunkt sollten diese auffallen und ggf. als Issues adressiert werden.\nNutzen Sie auch Issues für Dokumentation: Wenn Nutzer Fragen stellen, überlegen Sie, ob die Antwort in die offizielle Doku übernommen werden sollte. So wächst die Dokumentation organisch entlang der tatsächlichen Bedürfnisse.\n\n\n\nPositiv- und Negativbeispiele studieren\nSchlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf Projekte mit exzellenter Doku. Im Journal of Open Source Software (JOSS) werden z.B. Softwareartikel veröffentlicht, bei denen die zugehörigen Repositorien aufgrund des Review-Prozesses vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.\nNutzen Sie solche Ressourcen; sie ersparen einem das Rad neu zu erfinden. Allerdings: Adaptieren Sie sie auf Ihre Bedürfnisse – nicht jede Vorlage passt 1:1.",
     "crumbs": [
       "Home",
       "Serious",
@@ -1211,7 +1211,7 @@
     "href": "Writing/documentation.html#teil-automatisierte-dokumentationswerkzeuge",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "(Teil-)automatisierte Dokumentationswerkzeuge",
-    "text": "(Teil-)automatisierte Dokumentationswerkzeuge\nDie Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge erheblich senken. Gerade Forschende, die alleine programmieren, können von (teil-)automatisierter Dokumentation 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, wann ihr Einsatz sinnvoll oder notwendig ist:\n\nJupyter Notebooks und literate programming\nEin mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [7]. 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:\n\nals Tutorials/Beispiel-Workflows, die Nutzer interaktiv nachvollziehen können, und\nals Reproduzierbarkeits-Dokumentation für analytische Prozesse.\n\nWenn 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).\nNotebooks 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, wenn der Hauptanwendungsfall die Durchführung von Analysen oder Datenverarbeitungen ist, die man Schritt für Schritt demonstrieren kann.\n\n\n\n\n\n\nVorsicht bei Python-Notebooks\n\n\n\nNotebooks erfordern eine lauffähige Umgebung – das heißt, Sie müssen darauf achten, dass alle Abhängigkeiten im Notebook deklariert sind oder ggf. nachinstalliert werden und die Daten zugänglich sind.\nEs hat sich gezeigt, dass Notebooks aus Publikationen oft nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen fehlen.\nDeshalb: Wenn Sie Notebooks als Doku nutzen, stellen Sie sicher, dass sie leicht ausführbar sind (z. B. durch Bereitstellen von Umgebungsdateien wie environment.yml oder Dockerfiles, kleinen Beispieldatensätzen und klaren Anweisungen im Notebook). Ggf. kann man zusätzlich auch reine Markdown/HTML-Exporte von evaluierten Notebooks exportieren und dem Repo beilegen, damit zumindest statisch die Inhalte einsehbar sind.\n\n\n\nWann sollten Sie Notebooks nutzen?\nNotebooks sind quasi Goldstandard, um wissenschaftliche Analysen nachvollziehbar zu machen. In Projekten, wo es um Data Science Workflows oder interaktive Exploration geht, sollten Notebooks stark erwogen werden, während für ein reines Tool/Script eine gut geschriebene README mit Beispielausgabe ausreichend sein kann.\n\n\n\nSphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)\n\n\n\n\n\n\n\nPrinzip\n\n\n\nAb einer Codebasis > einige tausend Zeilen oder >5 nontriviale Module sollte eine generierte Dokumentation bereitstehen.\n\nFür umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll sein, eine Dokumentationswebsite zu generieren. Tools wie Sphinx (zusammen mit ReadTheDocs für Hosting) oder MkDocs erlauben es, aus Markdown/reStructuredText-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 Continuous Integration lassen sich diese Seiten bei jedem Git-Push automatisch aktualisieren.\nFür die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind[1] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.\nSolche Tools sind sinnvoll, wenn die Dokumentation sehr groß oder öffentlich weit verbreitet 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. 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.\n\nWann sollten Sie eine statische Website generieren?\nVerpflichtend ist so ein Tool selten, höchstens wenn Förderprogramme oder Journals ein dokumentationsseitiges HTML-Manual verlangen. Wenn Sie jedoch planen, Ihre Software z. B. über Jahre zu pflegen und ggf. einem Journal wie JOSS vorzustellen, dann erwartet die Community meist, dass zumindest eine Sphinx/Doxygen-Doku für die API (s.u.) existiert.\n\n\n\nDocstrings und API-Dokumentationsgeneratoren\n\n\n\n\n\n\n\nPrinzip\n\n\n\nBenutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden, ist dieses notwendig. Generation dieser Dokumentation ist daher der beste Weg.\n\n5 kurz für: “Documentation String”Nutzen Sie die Möglichkeit, Dokumentation direkt im Quellcode unterzubringen, z. B. in Form von Docstrings5 (mehrzeilige Strings in Funktionen/Klassen bei Python, Roxygen-Kommentare in R, Javadoc-Kommentare in Java, etc.).\nDiese 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 jede wichtige oder von außen sichtbare Funktion, Klasse oder Modul mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.\nWichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. Google Style Guide für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)[8]. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa pylint, können die Verwendung erzwingen.\nMit Tools, wie Sphinx, Javadoc, Doxygen, MkDocs,pdoc 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.\n\n\nVersionskontrolle und kontinuierliche Dokumentationspflege\n\n\n\n\n\n\n\nPrinzip\n\n\n\nDie beste Dokumentation ist die, die sich selbst aktualisiert.\n\nEine Form der Teil-Automatisierung ist es, die Dokumentation an den Entwicklungs-Workflow zu koppeln. So sollte die Dokumentation im selben Versionskontrollsystem (Git) liegen wie der Code, damit Änderungen synchron nachverfolgt werden. Es empfiehlt sich, bei jedem größeren Code-Update zu prüfen, ob die Doku noch stimmt (das kann man sich z. B. als Punkt in Pull-Request-Reviews notieren oder per Issue-Template abfragen). Für Projekte mit Continuous Integration (CI) kann man sogar automatisierte Checks einrichten, die z. B. prüfen, ob die Doku gebaut werden kann oder ob Docstrings fehlen. Einige CI-Skripte generieren bei jedem Commit eine frische Doku (z. B. mittels Sphinx) und veröffentlichen sie – so ist garantiert, dass die aktuelle Codeversion immer eine aktuelle Doku hat.\nSchlussendlich muss aber das Level an Automation für jedes Projekt individuell abgewogen werden.",
+    "text": "(Teil-)automatisierte Dokumentationswerkzeuge\nDie Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge erheblich senken. Gerade Forschende, die alleine programmieren, können von (teil-)automatisierter Dokumentation 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, wann ihr Einsatz sinnvoll oder notwendig ist:\n\nJupyter Notebooks und literate programming\nEin mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [8]. 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:\n\nals Tutorials/Beispiel-Workflows, die Nutzer interaktiv nachvollziehen können, und\nals Reproduzierbarkeits-Dokumentation für analytische Prozesse.\n\nWenn 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).\nNotebooks 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, wenn der Hauptanwendungsfall die Durchführung von Analysen oder Datenverarbeitungen ist, die man Schritt für Schritt demonstrieren kann.\n\n\n\n\n\n\nVorsicht bei Python-Notebooks\n\n\n\nNotebooks erfordern eine lauffähige Umgebung – das heißt, Sie müssen darauf achten, dass alle Abhängigkeiten im Notebook deklariert sind oder ggf. nachinstalliert werden und die Daten zugänglich sind.\nEs hat sich gezeigt, dass Notebooks aus Publikationen oft nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen fehlen.\nDeshalb: Wenn Sie Notebooks als Doku nutzen, stellen Sie sicher, dass sie leicht ausführbar sind (z. B. durch Bereitstellen von Umgebungsdateien wie environment.yml oder Dockerfiles, kleinen Beispieldatensätzen und klaren Anweisungen im Notebook). Ggf. kann man zusätzlich auch reine Markdown/HTML-Exporte von evaluierten Notebooks exportieren und dem Repo beilegen, damit zumindest statisch die Inhalte einsehbar sind.\n\n\n\nWann sollten Sie Notebooks nutzen?\nNotebooks sind quasi Goldstandard, um wissenschaftliche Analysen nachvollziehbar zu machen. In Projekten, wo es um Data Science Workflows oder interaktive Exploration geht, sollten Notebooks stark erwogen werden, während für ein reines Tool/Script eine gut geschriebene README mit Beispielausgabe ausreichend sein kann.\n\n\n\nSphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)\n\n\n\n\n\n\n\nPrinzip\n\n\n\nAb einer Codebasis > einige tausend Zeilen oder >5 nontriviale Module sollte eine generierte Dokumentation bereitstehen.\n\nFür umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll sein, eine Dokumentationswebsite zu generieren. Tools wie Sphinx (zusammen mit ReadTheDocs für Hosting) oder MkDocs erlauben es, aus Markdown/reStructuredText-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 Continuous Integration lassen sich diese Seiten bei jedem Git-Push automatisch aktualisieren.\nFür die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch sind[3] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.\nSolche Tools sind sinnvoll, wenn die Dokumentation sehr groß oder öffentlich weit verbreitet 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. 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.\n\nWann sollten Sie eine statische Website generieren?\nVerpflichtend ist so ein Tool selten, höchstens wenn Förderprogramme oder Journals ein dokumentationsseitiges HTML-Manual verlangen. Wenn Sie jedoch planen, Ihre Software z. B. über Jahre zu pflegen und ggf. einem Journal wie JOSS vorzustellen, dann erwartet die Community meist, dass zumindest eine Sphinx/Doxygen-Doku für die API (s.u.) existiert.\n\n\n\nDocstrings und API-Dokumentationsgeneratoren\n\n\n\n\n\n\n\nPrinzip\n\n\n\nBenutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden, ist dieses notwendig. Generation dieser Dokumentation ist daher der beste Weg.\n\n5 kurz für: “Documentation String”Nutzen Sie die Möglichkeit, Dokumentation direkt im Quellcode unterzubringen, z. B. in Form von Docstrings5 (mehrzeilige Strings in Funktionen/Klassen bei Python, Roxygen-Kommentare in R, Javadoc-Kommentare in Java, etc.).\nDiese 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 jede wichtige oder von außen sichtbare Funktion, Klasse oder Modul mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.\nWichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. Google Style Guide für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen)[9]. Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa pylint, können die Verwendung erzwingen.\nMit Tools, wie Sphinx, Javadoc, Doxygen, MkDocs,pdoc 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.\n\n\nVersionskontrolle und kontinuierliche Dokumentationspflege\n\n\n\n\n\n\n\nPrinzip\n\n\n\nDie beste Dokumentation ist die, die sich selbst aktualisiert.\n\nEine Form der Teil-Automatisierung ist es, die Dokumentation an den Entwicklungs-Workflow zu koppeln. So sollte die Dokumentation im selben Versionskontrollsystem (Git) liegen wie der Code, damit Änderungen synchron nachverfolgt werden. Es empfiehlt sich, bei jedem größeren Code-Update zu prüfen, ob die Doku noch stimmt (das kann man sich z. B. als Punkt in Pull-Request-Reviews notieren oder per Issue-Template abfragen). Für Projekte mit Continuous Integration (CI) kann man sogar automatisierte Checks einrichten, die z. B. prüfen, ob die Doku gebaut werden kann oder ob Docstrings fehlen. Einige CI-Skripte generieren bei jedem Commit eine frische Doku (z. B. mittels Sphinx) und veröffentlichen sie – so ist garantiert, dass die aktuelle Codeversion immer eine aktuelle Doku hat.\nSchlussendlich muss aber das Level an Automation für jedes Projekt individuell abgewogen werden.",
     "crumbs": [
       "Home",
       "Serious",
@@ -1237,7 +1237,7 @@
     "href": "Writing/documentation.html#fazit",
     "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)",
     "section": "Fazit",
-    "text": "Fazit\nDie hier präsentierten Anforderungen und Empfehlungen bieten einen Leitfaden für die Dokumentation von Forschungssoftware in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit zu erreichen.\nIndem 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.\nSo schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft[9, Leitlinie 12]: 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 Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung 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: Gut dokumentierte Forschungscode ist nachhaltige Forschung.",
+    "text": "Fazit\nDie hier präsentierten Anforderungen und Empfehlungen bieten einen Leitfaden für die Dokumentation von Forschungssoftware in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit zu erreichen.\nIndem 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.\nSo schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft[10, Leitlinie 12]: 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 Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung 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: Gut dokumentierte Forschungscode ist nachhaltige Forschung.",
     "crumbs": [
       "Home",
       "Serious",
diff --git a/dist/sitemap.xml b/dist/sitemap.xml
index c66ffaf..8b6f049 100644
--- a/dist/sitemap.xml
+++ b/dist/sitemap.xml
@@ -82,6 +82,6 @@
   
   
     https://drezil.de/Writing/documentation.html
-    2025-06-05T17:11:16.330Z
+    2025-06-05T17:17:06.919Z