From 6202af618ab6d9c397a9664308dfebfb82a85f69 Mon Sep 17 00:00:00 2001 From: Nicole Dresselhaus Date: Thu, 5 Jun 2025 09:56:37 +0200 Subject: [PATCH] much more rework. --- background/BACKGROUND.html | 381 ++++++++++---- background/BACKGROUND.md | 556 +++++++++++--------- background/background.bib | 999 +++++++++++++++++++++++++++++------- background/extra-styles.css | 3 + 4 files changed, 1407 insertions(+), 532 deletions(-) create mode 100644 background/extra-styles.css diff --git a/background/BACKGROUND.html b/background/BACKGROUND.html index 5a19fc3..6f958f0 100644 --- a/background/BACKGROUND.html +++ b/background/BACKGROUND.html @@ -2,7 +2,7 @@ - + @@ -2151,35 +2151,68 @@ vertical-align: -.125em; .bi-suitcase2::before { content: "\f902"; } .bi-vignette::before { content: "\f903"; } - + + - + - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -2205,8 +2238,8 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
  • Format und Struktur der Dokumentation -

    Diese Dateien sollten konsistent formatiert und benannt sein, damit sie leicht auffindbar sind. Sie kommen ohne spezielle Tools aus – ein einfacher Texteditor genügt zum Bearbeiten. Auch Wiki-Seiten (etwa in GitHub) können genutzt werden, sind aber weniger dauerhaft versioniert im Vergleich zu Dateien im Code-Repository selbst. Die Dokumentation sollte möglichst im Repository selbst liegen, um sicherzustellen, dass sie gemeinsam mit dem Code versioniert, verteilt und archiviert wird. Externe Dokumentationswebsites sind für kleine Projekte oft Overkill und können im schlimmsten Fall verwaisen.

    +

    Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie leicht auffindbar sind.

    -
    -

    Keine proprietären Formate oder Abhängigkeit von Werkzeugen

    -

    Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown, reStructuredText). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil des Versionskontrollsystems. Ein Markdown-Dokument hingegen kann gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Markdown/Plaintext erfüllt die Bedingung der offenen Langzeitarchivierung[4] (im Gegensatz etwa zu einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 Jahren evtl. nicht mehr läuft). Im Sinne der Digital Longevity ist eine statische HTML- oder PDF-Version der Dokumentation (automatisch generiert aus Markdown via pandoc) als Teil der Release-Artefakte sinnvoll. Wichtig ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku bleibt.

    -
    -
    +

    Übersichtlichkeit und Navigierbarkeit

    -

    Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit Leser schnell die gesuchten Informationen finden. Eine logische Gliederung hilft unterschiedlichen Nutzergruppen gezielt das Relevante zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine Abschnittsübersicht am Anfang nützlich sein. Markdown bietet z. B. automatische TOC-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an einem Ort) und Wiederholungen zu vermeiden. Das Mantra “Don’t Repeat Yourself” gilt auch für Dokumentation.

    + +
    +
    +
    + +
    +
    +Prinzip +
    +
    +
    +

    “Don’t Repeat Yourself”: Alle Informationen zu einem Thema (Installation/Nutzung/…) an derselben Stelle sammeln und keinesfalls mehrfach pflegen.

    +
    +

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

    +

    Achten Sie darauf, pro Abschnitt nur zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an einem Ort) und Wiederholungen zu vermeiden. Das Mantra “Don’t Repeat Yourself” gilt auch für Dokumentation.

    -
    +

    Beispiele, Codeblöcke und ggf. Abbildungen einbinden

    -

    Nutzen Sie die Möglichkeiten von Markdown, um die Dokumentation lebendig zu gestalten. Zeigen Sie Code-Beispiele als formatierte Codeblöcke, fügen Sie Links zu weiterführenden Ressourcen ein, oder binden Sie bei Bedarf Abbildungen ein (etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche, etc.). Achten Sie dabei auf Dateigrößen und Formate (Bilder als PNG/JPG, Diagramme wenn möglich als SVG für Langlebigkeit). Falls Diagramme der Architektur oder Workflow-Abbildungen hilfreich sind, können diese mit simplen Mitteln erstellt werden (zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder graphviz). Diese Visualisierungen sind jedoch nur dann einzusetzen, wenn sie echten Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im Zweifel hat textuelle Beschreibung Vorrang, um nicht vom Prinzip “keep it simple” abzuweichen.

    +

    Nutzen Sie die Möglichkeiten von Markdown, um die Dokumentation lebendig zu gestalten. Zeigen Sie Code-Beispiele als formatierte Codeblöcke, fügen Sie Links zu weiterführenden Ressourcen ein, oder binden Sie bei Bedarf Abbildungen ein (etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche, etc.).

    +

    Achten Sie dabei auf Dateigrößen und Formate (Bilder als PNG/JPG, Diagramme wenn möglich als SVG für Langlebigkeit). Falls Diagramme der Architektur oder Workflow-Abbildungen hilfreich sind, können diese mit simplen Mitteln erstellt werden3.

    +

    3 zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder graphviz

    Diese Visualisierungen sind jedoch nur dann einzusetzen, wenn sie echten Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im Zweifel hat textuelle Beschreibung Vorrang, um nicht vom Prinzip “keep it simple” abzuweichen.

    Fazit Format und Struktur

    @@ -2413,27 +2521,35 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
  • ohne spezielle Umgebung lesbar sein

    • Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software (und deren Doku) auffindbar und zugänglich zu machen, ohne Hürden. Eine gut gepflegte README in Markdown erfüllt diese Anforderungen in den meisten Fällen optimal.

    -

    Die Dokumentation selbst

    -
    -

    Prinzip 1: Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?

    +
    +
    +
    + +
    +
    +Prinzip +
    +
    +
    +

    Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?

    +

    Gerade weil Forschende wenig Zeit haben, muss die Dokumentation effizient gestaltet sein – sie soll alle wichtigen Informationen enthalten, aber auch nicht unnötig ausschweifen. Für typische Forschungssoftware-Projekte in den Geisteswissenschaften wird ein Umfang von maximal ca. 10 Seiten (bei Bedarf verteilt auf mehrere Dateien) als ausreichend erachtet. Dieser Richtwert verhindert, dass die Doku zu einer unüberschaubaren Abhandlung wird, und zwingt zur Fokussierung auf das Wesentliche. Wichtig ist der Inhalt, nicht die Länge: eine kürzere, aber inhaltsreiche Dokumentation ist besser als eine lange, die nichts aussagt.

    Umfang und Fokus der Dokumentation

    -

    Ein effizienter Umfang lässt sich erreichen, indem sie alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles andere skippen. Negativbeispiele umfassen:

    +

    Ein effizienter Umfang lässt sich erreichen, indem sie alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles andere skippen.

    +
    +

    Negativbeispiele umfassen:

      -
    • jeder interne Programmiertrick wird erläutert – Quellcode-Kommentare richten sich an Entwickler, während die Nutzerdokumentation sich auf Nutzung und Kontext beschränkt
      • +
    • jeder interne Programmiertrick wird erläutert – Quellcode-Kommentare richten sich an Entwickler*innen, während die Nutzendendokumentation sich auf Nutzung und Kontext beschränkt
    • seitenlange Theorieabhandlungen (verweisen Sie stattdessen auf Papers)
    • generische Erklärungen bekannter Technologien (man muss Git oder Python nicht in der Doku erklären, sondern kann referenzieren)
    +

    Halten Sie auch die Sprache prägnant:

    • kurze Absätze
      • @@ -2450,12 +2566,12 @@ Markierung für mich -.-

    Fügen Sie zur Not eine kurze Übersicht/Zusammenfassung am Anfang ein, die das Wichtigste in Kürze nennt – viele Leser entscheiden in wenigen Minuten, ob sie eine Software weiter betrachten oder nicht, und hier zählt der erste Eindruck.

    -
    +

    Priorisierung bei Zeitmangel

    -

    Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwicklerdokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern nötig, um den Hauptnutzerfluss nicht zu überfrachten.

    +

    Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwickler*innendokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern nötig, um den Hauptnutzerfluss nicht zu überfrachten.

    Minimaldokumentation: kurze Kommentare

    -

    Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices[2] 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[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).

    Verlinkte Dokumentation ist auch Dokumentation

    @@ -2463,37 +2579,50 @@ Markierung für mich -.-

    Fokus auf Nutzer*innen - nicht Entwickler*innen

    -

    Stellen Sie sich beim Schreiben der Doku die verschiedenen Nutzerrollen vor: “Zukünftiges Ich”, Kolleg*innen, Fachforscher anderer Disziplin und ggf. Software-Entwickler, die den Code erweitern. Jede dieser Gruppen möchte bestimmte Dinge wissen.

    -

    Forscher*innen fragen:

    +

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

    +

    Forschende fragen:

    • Was kann das Tool?
    • Wie benutze ich es?
    • In welchem Kontext steht es?
    -

    Entwickler*innen fragen:

    +

    Entwicklende Personen fragen:

    • Wie kann ich beitragen?
    • Wie funktioniert es unter der Haube?
    -

    Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für Entwickler (z. B. Code-Struktur, To-do-Liste) können separat oder später ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwicklerdokus ohnehin nicht nötig – hier reicht es, den Code gut zu kommentieren und eventuell eine grobe Architekturübersicht bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, das Nutzen und Verstehen der Software von außen zu ermöglichen.

    +

    Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für Entwickler*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwickler*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code gut zu kommentieren und eventuell eine grobe Architekturübersicht bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, das Nutzen und Verstehen der Software von außen zu ermöglichen.

    -
    +

    Und anschließend?

    -

    Wenn der Zeitmangel vorüber ist[^als ob DAS je der Fall wäre -.-], sollte man nach und nach das folgende Kapitel umsetzen.

    -
    +

    Wenn der Zeitmangel vorüber ist4, sollte man nach und nach das folgende Kapitel umsetzen.

    +

    4 als ob DAS je der Fall wäre -.-

    Was macht eine gute Dokumentation aus

    Nutzungshilfen außerhalb der Dokumentation

    -

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

    +

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

    Fü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.

    Prinzipien: FAIR und ENDINGS

    -

    Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[citation-needed?] und den ENDINGS-Prinzipien[4] steht.

    Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit. Unsere Empfehlungen, etwa ein statisches Markdown-README beizulegen, die Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu machen, setzen genau diese Vorgaben um.
    -

    Gute Dokumentation bedeutet daher u.a.

    +

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

    + +
    +
    +
    + +
    +
    +ENDINGS-Prinzipien +
    +
    +
    +

    Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit. Unsere Empfehlungen, etwa ein statisches Markdown-README beizulegen, die Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu machen, setzen genau diese Vorgaben um.

    +
    +

    Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von

    • Reproduzierbarkeit (Installation, Daten, Beispiele),
    • Offenheit (Lizenz, offene Formate) und
      • @@ -2503,7 +2632,7 @@ Markierung für mich -.-

    Kontinuierliche Verbesserung und Feedback

    -

    Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:

    +

    Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:[citation-needed?]

    • frü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.).
    • Planen 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.
      • @@ -2530,17 +2659,19 @@ Markierung für mich -.-

      Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist, könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der Ergebnisse).

      Notebooks senken die Hürde, weil Nutzer direkt experimentieren können, und fördern transparente Forschung, da Code, Ergebnisse und Beschreibung 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.

      -
      +
      -Warnung +Vorsicht bei Python-Notebooks
      -

      Notebooks erfordern allerdings eine lauffähige Umgebung – das heißt, Sie müssen darauf achten, dass alle Abhängigkeiten im Notebook deklariert sind und die Daten zugänglich sind. Es hat sich gezeigt, dass Notebooks aus Publikationen oft nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen fehlen. Deshalb: 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 Notebooks auch in reine Markdown/HTML exportieren und dem Repo beilegen, damit zumindest statisch die Inhalte einsehbar sind.

      +

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

      +

      Es hat sich gezeigt, dass Notebooks aus Publikationen oft nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen fehlen.

      +

      Deshalb: 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.

      @@ -2550,35 +2681,65 @@ Warnung

      Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)

      -
      -

      Prinzip 2: ab einer Codebasis > einige tausend Zeilen oder >5 Module lohnt es sich, eine generierte Dokumentation bereitzustellen, um (auch selbst) den Überblick zu behalten.

      + +
      +
      +
      +
      -

      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[4] – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar.

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

      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?

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

      -
      +

      Docstrings und API-Dokumentationsgeneratoren

      -
      -

      Prinzip 3: Benutzt jemand die Software nur braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden ist dieses angeraten.

      + +
      +
      +
      +
      -

      Nutzen Sie die Möglichkeit, Dokumentation direkt im Quellcode unterzubringen, z. B. in Form von [Docstrings][] (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). 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.

      +
      +Prinzip +
      +
      +
      +

      Benutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden, ist dieses notwendig.

      +
      +

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

      Der Einsatz solcher Tools ist besonders dann sinnvoll, wenn Ihre Forschungssoftware über eine Programmierschnittstelle (API) verfügt, die von anderen genutzt werden soll, oder wenn das Projekt größer wird und die interne Struktur komplexer ist. In solchen Fällen kann eine API-Referenz (automatisch aus dem Code erzeugt) eine erhebliche Hilfe sein.

      -

      Verpflichtend wird dieser Ansatz etwa, wenn Sie ein Bibliothekspaket veröffentlichen (z. B. ein R-Package in CRAN oder Python-Package auf PyPI) – dort sind Docstrings und generierte Dokumentation quasi Standard. Für ein einmaliges Analyse-Skript in den Digital Humanities ist eine voll ausgebaute API-Doku vielleicht nicht nötig; hier reicht möglicherweise ein inline kommentierter Code. Häufig wandeln sich solche Analyse-Skripte aber über Zeit, sodass hier auch weitere Prinzipien guter Software[citation-needed?], wie Modularisierung empfohlen sind um gegebene Ansätze einfacher zu übertragen.

      -

      Prinzip: Benutzt jemand die Software nur braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden ist dieses angeraten.

      Versionskontrolle und kontinuierliche Dokumentationspflege

      -
      -

      Prinzip 4: Die beste Dokumentation ist die, die sich selbst schreibt.

      + +
      +
      +
      +
      -

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

      Dieses Level an Automation ist für kleine Projekte evtl. zu viel, aber das Prinzip “Dokumentation versionieren” ist allgemeingültig, um die Entwicklungshistorie konsistent zu halten.
      +
      +Prinzip +
      +
      +
      +

      Die beste Dokumentation ist die, die sich selbst aktualisiert.

      +
      +

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

      +

      Schlussendlich muss aber das Level an Automation für jedes Projekt individuell abgewogen werden.

      @@ -2592,30 +2753,28 @@ Warnung
    • Installation & Voraussetzungen: Sind alle Schritte, um die Software lauffähig zu machen, dokumentiert (inkl. Dependencies, evtl. mit Installationsbefehlen)? Ist ersichtlich, welche Umgebung nötig ist (OS, Hardware)?
    • Grundlegende Nutzung: Gibt es eine Anleitung oder Beispiele, wie man die Software verwendet (Eingabe -> Ausgaben)? Ist mindestens ein typischer Workflow beschrieben, idealerweise mit Beispielinput und -output?
    • Optionen & Schnittstellen: Falls relevant – sind alle wichtigen Funktionen, Befehlsoptionen oder API-Methoden dokumentiert? (Nicht unbedingt jede intern, aber alles, was ein Nutzer aufrufen könnte). Für APIs: Sind Parameter und Rückgaben erläutert?
      • -
    • Validierung & Einschränkungen: Werden Annahmen und Grenzen der Software genannt? Weiß eine Nutzerin, welche Fälle nicht abgedeckt sind oder worauf zu achten ist (z. B. Datenqualität, maximale Größen)? Transparenz hier verhindert Frustration.
      • +
    • Validierung & Einschränkungen: Werden Annahmen und Grenzen der Software genannt? Weiß ein*e Nutzer*in, welche Fälle nicht abgedeckt sind oder worauf zu achten ist (z. B. Datenqualität, maximale Größen)? Transparenz hier verhindert Frustration.
    • Hintergrund & Referenzen: Sind die wichtigsten konzeptionellen Hintergründe oder Referenzen angegeben? (Z. B. theoretische Grundlagen, Algorithmen, Literaturverweise). Das muss kein Essay sein, aber ein paar Sätze + Referenzen schaffen Vertrauen in die wissenschaftliche Fundierung.
    • Kontakt & Weiterführung: Ist angegeben, wie man Hilfe bekommt oder Fehler melden kann (Issue-Tracker, E-Mail)? Gibt es Hinweise für Beiträge (falls erwünscht) oder zumindest die Information, wer die Autor*innen sind?
    • Rechtliches & Zitation: Liegt die Lizenz bei und wird sie genannt? Sind Infos zum Zitieren der Software vorhanden (z. B. “Bitte zitieren Sie DOI XYZ”)? Das stellt sicher, dass die Software nachnutzbar und akademisch kreditiert wird.
    • Aktualität & Version: Entspricht die Dokumentation der aktuellen Softwareversion? (Check: Versionsnummern, Datumsangaben). Veraltete Doku kann schlimmer sein als keine – planen Sie also ein, die Doku mit jedem Release kurz zu überprüfen.
    • Konsistenz & Stil: Wird ein einheitlicher Ton und Stil durchgehalten? (z. B. durchgehende Verwendung gleicher Begriffe für Konzepte, Sprache entweder Deutsch oder Englisch einheitlich je nach Zielgruppe). Kleinliche Fehler (Tippfehler, kaputte Links) sind auszumerzen, da sie Nutzer abschrecken.
      • -

      Diese Checkliste kann vor einem “Release” der Software durchgegangen werden, ähnlich einem Review-Prozess (vgl. JOSS Review-Kriterien, die viele dieser Punkte abdecken). Sie hilft zu entscheiden, was noch dokumentiert werden muss und was eventuell weggelassen werden kann. Alles, was für die obigen Punkte nicht relevant ist, kann man tendenziell aus der Hauptdokumentation herauslassen. Beispielsweise interne Code-Refaktorierungsdetails oder historische Anekdoten zur Entwicklung gehören eher ins interne Changelog oder in Blog-Posts, nicht in die Nutzerdokumentation.

      -
      -
      -

      Zusammenfassung Best Practices

      +

      Diese Checkliste kann vor einem “Release” der Software durchgegangen werden, ähnlich einem Review-Prozess (vgl. JOSS Review-Kriterien, die viele dieser Punkte abdecken). Sie hilft zu entscheiden, was noch dokumentiert werden muss und was eventuell weggelassen werden kann. Alles, was für die obigen Punkte nicht relevant ist, kann man tendenziell aus der Hauptdokumentation herauslassen.

    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.

    -

    Eine gute Dokumentation erzählt eine klare Geschichte über die Software, anstatt den Leser mit irrelevanten Details zu verlieren. Mit den richtigen Werkzeugen und Prinzipien an der Hand kann selbst unter Zeitdruck eine qualitativ hochwertige Dokumentation entstehen – zur Freude aller, die mit der Forschungssoftware arbeiten möchten.

    -

    Wissenschaftlich fundierte Best Practices – von Ten Simple Rules for Documenting Scientific Software[1] bis zu den ENDINGS-Principles[4] – untermauern diesen Katalog. Die Umsetzung dieser Richtlinien wird dazu beitragen, dass Forschungssoftware aus den Geisteswissenschaften nicht nur kurzfristig von ihren Autor*innen genutzt wird, sondern langfristig von Dritten verstanden, validiert und weiterentwickelt werden kann. So schließt sich der Kreis zwischen guter Softwareentwicklung und guter Wissenschaft: 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.

    +

    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[7, 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.

    +

    Tabellarische Übersicht der Dokumentations-Bestandteile

    @@ -2704,7 +2863,7 @@ Warnung

    Referenz Software

      -
    • git: Versionskontrollsystem
      • +
    • git: Versionskontrollsystem
    • graphviz: Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg
    • Markdown: Mittlerweile DER Standard bei plaintext-Dokumenten
    • mermaid.js: Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden
      • @@ -2712,30 +2871,34 @@ Warnung
    • pylint: Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.
    • rst: Alternative zu Markdown.
    +

    Bibliographie

    -
    -
    1.
    Prlić, Andreas, und James B. Procter. 2012. Ten Simple Rules for the Open Development of Scientific Software. PLOS Computational Biology 8. Public Library of Science: e1002802. https://doi.org/10.1371/journal.pcbi.1002802.
    -
    -
    -
    2.
    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.
    +
    +
    1.
    Endings Project Team. 2023. Endings Principles for Digital Longevity (Version 2.2.1).
    -
    3.
    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.
    +
    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.
    Endings Project Team. 2023. Endings Principles for Digital Longevity.
    +
    +
    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.
    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.
    +
    +
    4.
    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.
    +
    +
    +
    5.
    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.
    -
    6.
    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 20th International Conference on Electronic Publishing (01/01/16), Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. https://doi.org/10.3233/978-1-61499-649-1-87.
    +
    6.
    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.
    +
    +
    +
    7.
    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 , GPT-4.5},
+  author = {Dresselhaus, Nicole and deep research, GPT-4.5},
   title = {Anforderungskatalog für die Dokumentation von
     Forschungssoftware (Digital Humanities)},
   date = {2025-05-08},
@@ -2746,9 +2909,9 @@ Warnung
     theoretischen Grundlagen nachvollziehbar zu machen.}
 }
    Bitte zitieren Sie diese Arbeit als:
    -Dresselhaus, Nicole, and GPT-4.5. 2025. “Anforderungskatalog für -die Dokumentation von Forschungssoftware (Digital Humanities).” -May 8, 2025. +Dresselhaus, Nicole, and GPT-4.5 deep research. 2025. +“Anforderungskatalog für die Dokumentation von Forschungssoftware +(Digital Humanities).” May 8, 2025.