Listen 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”).
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.--help dokumentiert). --help dokumentiert). 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.
-Ein effizienter Umfang lässt sich erreichen, indem man sich auf die oben genannten Kernpunkte konzentriert und Ablenkendes weglässt. Dokumentieren Sie alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist, und skippen Sie alles andere. Zum Beispiel muss nicht jeder interne Programmiertrick erläutert werden – Quellcode-Kommentare richten sich an Entwickler, während die Nutzerdokumentation sich auf Nutzung und Kontext beschränkt. Verzichten Sie auf seitenlange Theorieableitungen (verweisen Sie stattdessen auf Papers) und auf 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, Listen und einfache Sätze erhöhen die Lesbarkeit. Fachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet werden, aber erklären Sie sie, falls die Zielnutzer sie evtl. nicht kennen.
-Priorisierung: Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (“keine Dokumentation” ist keine Option). Good Enough Practices 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).
-Die Obergrenze von ~10 Seiten ist ein Richtwert. Umfangreiche Projekte könnten etwas mehr benötigen, sehr kleine Tools kommen mit einer Seite aus. Das Ziel ist, dass ein interessierter Nutzer die Dokumentation in überschaubarer Zeit durchsehen kann. Ein guter Test ist: Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen? Wenn ja, ist der Detailgrad angemessen. Wenn die Person hingegen nach 10 Seiten immer noch nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden. 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.
-Ein weiterer Tipp zur Effizienz: Nutzen 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. 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.
-Zum Fokus gehört auch, zwischen Nutzerdokumentation und Entwicklerdokumentation zu unterscheiden. 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. Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwicklerdokus 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.
-Abschließend sei betont: Ein kompakter, zielgerichteter Dokumentsatz, der genau die relevanten Infos liefert, erhöht die Wahrscheinlichkeit, dass er aktualisiert und genutzt wird. Umfangmonster schrecken ab und veralten schneller. Halten Sie die Dokumentation deshalb so knapp wie möglich, aber so ausführlich wie nötig – ganz im Sinne von Einsteins Prinzip, Dinge so einfach wie möglich zu machen, aber nicht einfacher.
+Prinzip 1: 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.
+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:
+Halten Sie auch die Sprache prägnant:
+erhöhen die Lesbarkeit.
+Fachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht kennen.
+Die Obergrenze von ~10 Seiten ist ein Richtwert. Umfangreiche Projekte könnten etwas mehr benötigen, sehr kleine Tools kommen mit einer Seite aus. Das Ziel ist, dass ein interessierter Nutzer die Dokumentation in überschaubarer Zeit durchsehen kann.
+Ein guter Test ist: Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?
+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.
+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.
+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).
+Nutzen 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.
+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:
+Entwickler*innen fragen:
+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.
+Wenn der Zeitmangel vorüber ist[^als ob DAS je der Fall wäre -.-], sollte man nach und nach das folgende Kapitel umsetzen.
+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.
+Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering[citation-needed?] und den ENDINGS-Prinzipien[4] steht.
Gute Dokumentation bedeutet daher u.a.
+Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche Softwarepraxis.
+Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:
+Schlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf Projekte mit exzellenter Doku. In der Journal of Open Source Software (JOSS) oder Journal of Open Research Software (JORS) werden oft Softwareartikel veröffentlicht, bei denen die zugehörigen Repositorien vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.
+Achten Sie darauf, wie diese Projekte ihre README strukturieren, welche Abschnitte vorhanden sind und welche nicht. Viele erfolgreiche Projekte haben z. B. eine ähnliche Reihenfolge: Introduction, Installation, Usage, Contributing, License, Citation – ein Muster, das sich bewährt hat.
+Ebenso gibt es von Initiativen wie der Software Sustainability Institute Blogposts mit Best Practices und sogar Vorlagen (Templates) für Dokumentation.
+Nutzen 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.
+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:
-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 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). Mit Tools wie Sphinx (für Python, aber grundsätzlich sprachunabhängig) können aus Docstrings automatisiert Webseiten oder PDF-Handbücher generiert werden. Sphinx liest z. B. die Python-Docstrings und erzeugt daraus strukturiert eine Dokumentation; Erweiterungen wie napoleon erlauben es, Google- oder Numpy-Style-Dokumentation direkt zu verarbeiten.
- -Ähnliche Generatoren gibt es für nahezu alle Sprachen: Javadoc für Java, Doxygen für C/C++ (und viele andere Sprachen), MkDocs oder pdoc für Python, etc.
-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. Doch sobald Funktionen von anderen aufgerufen oder das Projekt von mehreren entwickelt wird, sollte ein Dokumentationstool in Betracht gezogen werden, um den Aufwand gering zu halten und Einheitlichkeit zu gewährleisten.
-Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [6]. Diese erlauben es, ausführbaren Code mit erklärendem Text und Visualisierungen in einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei leisten: (1) als Tutorials/Beispiel-Workflows, die Nutzer interaktiv nachvollziehen können, und (2) als Reproduzierbarkeits-Dokumentation für analytische Prozesse. Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist, könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der Ergebnisse).
+Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind Jupyter Notebooks bzw. R Markdown Notebooks [6]. 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:
+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.
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.
Wann sind Notebooks verpflichtend? – Nie im strengen Sinne, aber sie 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.
+Notebooks 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.
+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 (ENDINGS-Prinzip) ist wichtig, dass diese Webseiten statisch sind – d.h. sie funktionieren ohne Server-Backends und bleiben auch offline nutzbar. Sphinx erfüllt dies, indem es reine HTML-Seiten erzeugt. 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.
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 existiert. Als Daumenregel: ab einer Codebasis > einige tausend Zeilen oder > 5 Module lohnt es sich, eine generierte Dokumentation bereitzustellen, um den Überblick zu behalten.
+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.
+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.
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.
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. Click oder 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.
+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.
+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.
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.
In bestimmten Fällen gibt es weitere Werkzeuge: z. B. Doxygen für automatisierte Code-Diagramme und Querverweise (gerne in C++-Projekten genutzt), oder Swagger/OpenAPI für automatische Dokumentation von Web-APIs. Wenn Ihre Forschungssoftware z. B. einen Webservice anbietet, kann Swagger eine interaktive API-Doku erzeugen. Ebenso können Literatur-Manager wie Manubot oder RMarkdown Bücher helfen, Code und Text zu integrieren (aber das geht über das hinaus, was die meisten DH-Projekte benötigen). Erwähnenswert ist noch Jupyter Book oder R Bookdown, womit man umfangreiche narrative Dokumentationen (inkl. Code) als Website/Book erstellen kann – nützlich, falls Ihre Dokumentation eher ein ausführlicher Lehrtext werden soll (z. B. wenn die Software einen ganzen methodischen Ansatz dokumentiert). Für den hier anvisierten Zweck (knackiger Doku-Katalog) sind solche Tools meist zu schwergewichtig.
-Es gibt kein universelles Muss, außer: Irgendeine Form der Doku ist Pflicht. Ob Sie nun per Hand Markdown schreiben oder Sphinx einsetzen, hängt von Kontext und Projektgröße ab. Allgemein gilt: Verwenden Sie Automatisierung wo immer möglich, um sich zu entlasten, aber vermeiden Sie Overhead durch Tools, die Sie nicht brauchen. Ein einzelnes historisches Analyse-Skript braucht kein Doxygen; ein komplexes DH-Toolkit mit API sollte hingegen Doxygen oder Sphinx nutzen, damit die Nutzer nicht den Code lesen müssen, um Funktionen zu verstehen. Denken Sie daran: “Die beste Dokumentation ist die, die sich selbst schreibt.” – dieses Motto aus der Literatur spielt darauf an, dass wir Tools nutzen sollen, die uns Schreibarbeit abnehmen. Perfekt autonom schreibt sich die Dokumentation zwar nie, aber moderne Werkzeuge können Routineaufgaben (z. B. Inhaltsverzeichnisse, Funktionsreferenzen, Formatierung) automatisieren. Dadurch bleibt Ihnen mehr Zeit für das inhaltliche Fine-Tuning der Texte.
-Um zu entscheiden, was dokumentiert wird (und was nicht), helfen etablierte Best Practices sowie Vorlagen aus der Community. Im Folgenden sind einige bewährte Richtlinien zusammengefasst, untermauert von Quellen, die bei der Priorisierung der Dokumentationsinhalte helfen:
-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: Was kann das Tool? Wie benutze ich es? In welchem Kontext steht es?. Entwickler*innen 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. Halten Sie sich stets vor Augen: Dokumentation ist primär für Menschen (nicht für Maschinen), daher schreiben Sie klar und vermeiden Sie unnötigen Jargon. Selbst wenn der Code “für sich spricht”, denken Sie daran, dass klare Erläuterungen später viel Zeit sparen.
-Um zu entscheiden, was dokumentiert wird (und was nicht), helfen etablierte Best Practices sowie Vorlagen aus der Community. Im Folgenden sind einige bewährte Richtlinien zusammengefasst.
Die folgenden Punkte fassen zusammen, was eine gute Dokumentation mindestens enthalten sollte. Sie können auch als Qualitäts-Checkliste dienen, um Ihre Dokumentation zu überprüfen:
@@ -2504,31 +2599,25 @@ WarnungDiese 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.
-Ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf Projekte mit exzellenter Doku. In der Journal of Open Source Software (JOSS) oder Journal of Open Research Software (JORS) werden oft Softwareartikel veröffentlicht, bei denen die zugehörigen Repositorien vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen. Achten Sie darauf, wie diese Projekte ihre README strukturieren, welche Abschnitte vorhanden sind und welche nicht. Viele erfolgreiche Projekte haben z. B. eine ähnliche Reihenfolge: Introduction, Installation, Usage, Contributing, License, Citation – ein Muster, das sich bewährt hat. Ebenso gibt es von Initiativen wie der Software Sustainability Institute Blogposts mit Best Practices und sogar Vorlagen (Templates) für Dokumentation. Nutzen 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.
-Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des Research Software Engineering und den ENDINGS-Prinzipien steht. Gutes Research Software Engineering fördert u.a. Nachhaltigkeit, Offenheit und Reproduzierbarkeit in der Softwareentwicklung. Dementsprechend legt unsere Dokumentations-Checkliste Wert auf Reproduzierbarkeit (Installation, Daten, Beispiele), Offenheit (Lizenz, offene Formate) und Nachhaltigkeit (Versionierung, Langlebigkeit der Doku). 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. Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche Softwarepraxis.
-Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice ist, 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). Nutzen 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.
+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.
Zusammenfassend helfen die genannten Best Practices dabei, die Dokumentation zielgerichtet zu gestalten: Dokumentiert wird, was dem Verständnis und der Nutzung dient; weggelassen wird, was überflüssig oder selbstverständlich ist. 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.
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.
-Wissenschaftlich fundierte Best Practices – von Ten Simple Rules for Documenting Scientific Software bis zu den ENDINGS-Principles – 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.
-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.
+Mit einer solchen Struktur und Herangehensweise lässt sich auch in einem kleinen Forschungsteam eine professionelle Dokumentation erzielen, die den Prinzipien von Open Science und nachhaltiger Softwareentwicklung gerecht wird. Die investierte Mühe wird durch Zeitgewinn bei Wiederverwendung und Erweiterung der Software mehr als aufgewogen. So wird die Forschungssoftware nicht zum einmaligen “Nebenprodukt”, sondern zu einem robusten, teilbaren Ergebnis wissenschaftlicher Arbeit.
-