From bb661ce672283ce77ce0ecbaf94c108c5a1f3dc3 Mon Sep 17 00:00:00 2001 From: Nicole Dresselhaus Date: Thu, 8 May 2025 15:50:36 +0200 Subject: [PATCH] added/formatted background --- background/BACKGROUND.html | 3041 +++++++++++++++++++ background/BACKGROUND.md | 828 +++++ background/background.bib | 69 + background/springer-humanities-brackets.csl | 421 +++ background/themes/nfdi.scss | 119 + 5 files changed, 4478 insertions(+) create mode 100644 background/BACKGROUND.html create mode 100644 background/BACKGROUND.md create mode 100644 background/background.bib create mode 100644 background/springer-humanities-brackets.csl create mode 100644 background/themes/nfdi.scss diff --git a/background/BACKGROUND.html b/background/BACKGROUND.html new file mode 100644 index 0000000..6089df8 --- /dev/null +++ b/background/BACKGROUND.html @@ -0,0 +1,3041 @@ + + + + + + + + + + +Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+

Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)

+
+ +
+
+

Ein Überblick und Best Practices für die Dokumantation von Forschungssoftware.

+
+
+ +
+
Autor:innen
+
Zugehörigkeiten
+ +
+

Nicole Dresselhaus

+
+
+

+ + Humboldt-Universität zu Berlin + +

+
+
+

GPT-4.5

+
+
+

+ + OpenAI + +

+
+
+ +
+ + +
+
Veröffentlichungsdatum
+
+

8. Mai 2025

+
+
+ + +
+ +
+
+
Zusammenfassung
+

Diese Dokumentation fasst zusammen, welche wissenschaftlichen Konzepte, Algorithmen und Theorien hinter der Software stehen. Sie dient dazu, den 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.

+

Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien [1–4].
+

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 insbesondere die Prinzipien des Endings-Projekts für digitale Langlebigkeit [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. 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. 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. Beispiel: “Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.” 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).

+
+
+

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 in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert. Eine Tabelle oder Auflistung der Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht die Klarheit.

Beispiel: “Eingabedatei: CSV mit Spalten Autor, Empfänger, …; Ausgabe: JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”
+
+
+

Code-Abhängigkeiten und technische Voraussetzungen

+

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

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.
+
    +
  • Typische Nutzungsszenarien und Workflows: Zeigen Sie anhand von 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 (“Getting Started”-Abschnitt). Beschreiben 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”). Diese Beispiele sollten realistisch und möglichst repräsentativ für wissenschaftliche Anwendungen sein. Nutzen Sie gerne kleine 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).
    • +
+
Faustregel: Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.
+
+

Wissenschaftlicher Hintergrund und theoretischer Kontext

+

Da es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform. Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.” Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst. Wichtig 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.

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

Bekannte Limitationen, Annahmen und Fehlermeldungen

+

Geben Sie ehrlich Auskunft über die Grenzen der Software. Welche Fälle werden nicht abgedeckt? Welche Annahmen über die Daten oder Anwendungsszenarien werden getroffen? Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. “funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”). Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit. Falls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden. Eine transparente Auflistung von Limitationen erhöht die Vertrauenswürdigkeit und hilft anderen, die Ergebnisse richtig einzuordnen. Auch 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 wie es behoben werden kann (z. B. “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.

+
+
+

Weiterentwicklung und Beitragsmöglichkeiten

+

Obwohl 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 Autor (E-Mail) gehört dazu. Ebenso können Community Guidelines skizziert werden: etwa Codierstandards 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…”.

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. 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. Diese Praxis entspricht auch den ENDINGS-Prinzipien, die verlangen, dass jede veröffentlichte Version eindeutig erkennbar ist und zitiert werden kann.

+
+
+

Zusammenfassung der inhaltlichen Anforderungen

+

Zusammengefasst sollte die Dokumentation alle W-Fragen beantworten: Was tut die Software, warum wurde sie geschrieben (wissenschaftlicher Zweck), wer soll sie nutzen, wie wird sie benutzt (Inputs, Outputs, Abläufe), womit läuft sie (Umgebung/Abhängigkeiten), unter welchen Bedingungen (Annahmen/Limitationen) und wohin können sich Nutzer wenden (Support/Zitation). All diese Punkte sorgen für Nachvollziehbarkeit (im Sinne von Reproduzierbarkeit der Ergebnisse) und Weiterverwendbarkeit (im Sinne von Adaptierbarkeit der Software für neue Kontexte).

+
+
+
+

Format und Struktur der Dokumentation

+

Für Forschende ohne viel Ressourcen muss die Dokumentation einfach zugänglich, leicht pflegbar und ohne Spezialsoftware erstellbar sein. Daher empfiehlt es sich, auf leichte Formate und eine klare Struktur zu setzen:

+
+

README.md als zentrales Dokument

+

Die Hauptdokumentation sollte als README in Markdown-Format im Hauptverzeichnis des Code-Repositoriums liegen. Dieses README fungiert als “Startseite” des Projekts und enthält idealerweise eine komprimierte Übersicht aller wichtigen Punkte: Zweck der Software, Kurzbeschreibung, Installation, kurzer Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie GitHub, GitLab etc. wird die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die Vorteile von Markdown sind die einfache Lesbarkeit in Rohform, die breite Unterstützung (auch in Renderern wie GitHub-Webansicht) und die Eignung für Versionierung (Textdatei im Git). So bleibt die Dokumentation eng mit dem Code verzahnt und unter Versionskontrolle – ein Prinzip, das auch von ENDINGS propagiert wird (Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden).

+
+
+

Strukturierte Unterteilung in weitere Dateien/Abschnitte

+ +
+
example-project/
+├── README.md
+├── CONTRIBUTING.md (optional)
+├── CHANGELOG.md    (optional)
+├── CITATION.md     (oder CITATION.cff)
+├── LICENSE
+├── data/           (optional)
+│   └── sample_data.csv
+├── docs/           (optional)
+│   ├── INSTALL.md
+│   └── USAGE.md
+├── examples/       (optional)
+│   └── example_workflow.ipynb
+└── src/
+    ├── script.py
+    └── module/
+        └── helper.py
+

Beispielhafter Struktur eines Code-Repositories

+

Sollte die Dokumentation umfangreicher sein, ist es sinnvoll, sie in logisch getrennte Abschnitte aufzuteilen. Dies kann innerhalb der README durch Überschriften geschehen oder durch zusätzliche Markdown-Dateien im 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.:

+
    +
  • README.md – Überblick (Ziel, Installation, kurzes Beispiel, Lizenz/Zitation)
    • +
  • docs/ Verzeichnis mit weiteren .md-Dateien für tiefergehende Dokumentation (optional)
    • +
  • CONTRIBUTING.md – Hinweise für Beiträger (falls relevant)
    • +
  • LICENSE – Lizenztext
    • +
  • CITATION.cff oder CITATION.md – wie zu zitieren.
    • +
+

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.

+
+
+

Keine proprietären Formate oder Abhängigkeit von Werkzeugen

+

Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown, reStructuredText). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil des Versionskontrollsystems. Ein Markdown-Dokument hingegen kann gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Zudem erlauben offene Formate eine leichtere Langzeitarchivierung: Gemäß Endings-Prinzip sollten Informationsressourcen in langfristig lesbaren Formaten vorliegen. Markdown/Plaintext erfüllt diese Bedingung (im Gegensatz etwa zu einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 Jahren evtl. nicht mehr läuft). Im Sinne der Digital Longevity ist eine statische HTML- oder PDF-Version der Dokumentation (automatisch generiert aus Markdown) als Teil der Release-Artefakte sinnvoll – so kann z. B. in jeder veröffentlichten Version ein PDF-Handbuch beigelegt werden, das später zitiert oder referenziert werden kann. Wichtig ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku bleibt.

+
+
+

Übersichtlichkeit und Navigierbarkeit

+

Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit Leser schnell die gesuchten Informationen finden. Eine logische Gliederung (wie in diesem Katalog: Einführung, Anforderungen, Installation, Nutzung, Hintergrund, etc.) hilft unterschiedlichen Nutzergruppen gezielt das Relevante zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine Abschnittsübersicht am Anfang nützlich sein. Markdown bietet z. B. automatische Toc-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an einem Ort). Wiederholungen sollten vermieden werden: lieber an einer Stelle ausführlich dokumentieren und sonst darauf verweisen, um Konsistenzprobleme zu vermeiden (“Don’t Repeat Yourself” gilt auch für Dokumentation). Bei ähnlichen Projekten können Sie sich an bestehenden Dokumentationsvorlagen orientieren: Viele erfolgreiche Open-Source-Projekte haben auf GitHub eine ähnliche README-Struktur, die als informelles Template dienen kann.

+
+
+

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.

+
+
+

Fazit Format und Struktur

+

Insgesamt gilt: Die Dokumentation sollte im gleichen Repository leben wie der Code, klar strukturiert und in einem einfach handhabbaren Format vorliegen. Sie soll ohne spezielle Umgebung lesbar sein – ein Nutzer, der das Repository klont oder herunterlädt, muss sofort Zugang zur Dokumentation haben. Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software (und deren Doku) auffindbar und zugänglich zu machen, ohne Hürden. Eine gut gepflegte README in Markdown erfüllt diese Anforderungen in den meisten Fällen optimal.

+
+
+
+

Umfang und Fokus der Dokumentation

+

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.

+
+
+

(Teil-)automatisierte Dokumentationswerkzeuge

+

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:

+
+

Docstrings und API-Dokumentationsgeneratoren

+

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.

+
+
+

Jupyter Notebooks und literate programming

+

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

+

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

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.

+
+
+

Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)

+

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.

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

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.

+
+
+

In-Code Hilfefunktionen und CL-Interface Doku

+

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.

+
+
+

Versionskontrolle und kontinuierliche Dokumentationspflege

+

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

Spezialfälle

+

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.

+
+
+

Wann ist was verpflichtend

+

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.

+
+
+
+

Best Practices, Vorlagen und Checklisten

+

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:

+
+

Orientierung an Nutzerbedürfnissen

+

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.

+
+
+

Checkliste für die Mindest-Dokumentation

+

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:

+
    +
  1. Zielklärung: Ist der Zweck der Software klar benannt und der wissenschaftliche Need begründet? (Falls nein, ergänzen: Warum existiert dieses Tool?)
    2. +
  2. 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)?
    3. +
  3. 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?
    4. +
  4. 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?
    5. +
  5. 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.
    6. +
  6. 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.
    7. +
  7. 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?
    8. +
  8. 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.
    9. +
  9. 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.
    10. +
  10. 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.
    11. +
+

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.

+
+
+

Positiv- und Negativbeispiele studieren

+

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.

+
+
+

Prinzipien: FAIR und ENDINGS

+

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.

+
+
+

Kontinuierliche Verbesserung und Feedback

+

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.

+
+
+

Zusammenfassung Best Practices

+

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.

+
+
+
+

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.

+

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.

+
+

Tabellarische Übersicht der Dokumentations-Bestandteile

+
+ + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Empfohlene Dokumentationselemente, Inhalte und Umfang. Diese Übersicht kann als Vorlage dienen, welche Komponenten ein Dokumentationspaket enthalten sollte. Je nach Projekt können einige Elemente wegfallen oder kombiniert werden – entscheidend ist, dass die Kerninformationen (siehe oben) nicht fehlen.
DokuelementInhalt/PurposeFormat/OrtUmfang
README (Hauptdoku)Zweck der Software; Kurzbeschreibung; Installationsanleitung; einfaches Nutzungsbeispiel; Lizenz- und KontaktinfoMarkdown im Root des Repos (statisch versioniert)1–2 Seiten
Eingabe/Ausgabe-GuideBeschreibung der erwarteten Inputs (Datenformat, Parameter) und generierten Outputs (Dateien, Berichte) inkl. BeispielenTeil der README oder separate Datei (z.B. USAGE.md)1 Seite (mit Beispielen)
Wissenschaftlicher HintergrundErläuterung der Methode, Theorie, Algorithmen; Verweise auf LiteraturREADME-Abschnitt “Hintergrund” oder separate Doku (BACKGROUND.md)0.5–1 Seite (plus Referenzen)
Bekannte LimitationenAuflistung von Einschränkungen, Annahmen, bekannten Problemen; ggf. WorkaroundsREADME-Abschnitt “Limitations” oder FAQ.md0.5 Seite
Beispiel-Workflow (Tutorial)Schritt-für-Schritt Anleitung mit einem realistischen Anwendungsfall (ggf. mit Code und Screenshot)Jupyter Notebook (.ipynb) im Repo examples/ Ordner oder Markdown in docs/1–3 Seiten / entsprechend Zellen
API-ReferenzTechnische Dokumentation von Funktionen/Klassen für Entwickler*innenAutomatisch generiert aus Docstrings (z.B. Sphinx in docs/ Ordner, HTML/PDF Ausgabe)Je nach Codegröße (ggf. umfangreich)
CONTRIBUTINGAnleitung für Beitragswillige: Code Style, Workflow, Tests, KontaktCONTRIBUTING.md im Repo0.5–1 Seite
LICENSE / CITATIONRechtliche Infos (Lizenztext); Zitationsleitfaden (Bevorzugte Zitierweise, DOI)Jeweils eigene Datei im Repo (Plain Text/Markdown)Kurz (Standardtext bzw. Referenz)
Release-InformationVersionshinweise, Änderungsprotokoll (Changelog)CHANGELOG.md oder Releases auf GitHubfortlaufend pro Version (Stichpunkte)
+
+
+
+

Schlusswort

+

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.

+ +
+
+ +

Literatur

+
+
1.
Prlić, Andreas, und James B Procter. 2012. Ten simple rules for documenting scientific software. PLoS Computational Biology 8. Public Library of Science: e1002802.
+
+
+
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.
+
+
+
3.
Katz, Daniel S, Kyle E Niemeyer, und Arfon M Smith. 2021. The Journal of Open Source Software (JOSS). PeerJ Computer Science 7. PeerJ Inc.: e432.
+
+
+
4.
Endings Project. 2020. Endings Principles for Digital Longevity.
+
+
+
5.
Smith, Arfon M, Daniel S Katz, Kyle E Niemeyer, FORCE11 Software Citation Working Group, u. a. 2016. Software citation principles. PeerJ Computer Science 2. PeerJ Inc.: e86.
+
+
+
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. Positioning and Power in Academic Publishing: Players, Agents and Agendas 20. IOS Press: 87–90.
+
+

Zitat

Mit BibTeX zitieren:
@online{dresselhaus2025,
+  author = {Dresselhaus, Nicole and , GPT-4.5},
+  title = {Anforderungskatalog für die Dokumentation von
+    Forschungssoftware (Digital Humanities)},
+  date = {2025-05-08},
+  langid = {de},
+  abstract = {Diese Dokumentation fasst zusammen, welche
+    wissenschaftlichen Konzepte, Algorithmen und Theorien hinter der
+    Software stehen. Sie dient dazu, den Nutzer*innen zu helfen, die
+    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. +
+ + +
+ + + + + \ No newline at end of file diff --git a/background/BACKGROUND.md b/background/BACKGROUND.md new file mode 100644 index 0000000..28df726 --- /dev/null +++ b/background/BACKGROUND.md @@ -0,0 +1,828 @@ +--- +tags: + - Writing +cssclasses: + - table-wide + - table-wrap +title: + "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital + Humanities)" +description: | + Ein Überblick und Best Practices für die Dokumantation von Forschungssoftware. +abstract: | + Diese Dokumentation fasst zusammen, welche wissenschaftlichen Konzepte, + Algorithmen und Theorien hinter der Software stehen. Sie dient dazu, den + Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen. +lang: de +date: 2025-05-08 +authors: + - name: Nicole Dresselhaus + affiliation: + - name: Humboldt-Universität zu Berlin + url: https://hu-berlin.de + email: nicole.dresselhaus@hu-berlin.de + correspondence: true + orcid: 0009-0008-8850-3679 + roles: + - Conceptualization + - Supervision + - Validation + - "Writing – review & editing" + - name: GPT-4.5 + url: https://chatgpt.com + affiliation: + - name: OpenAI + url: https://openai.com + roles: + - investigation + - "Writing – original draft" +citation: true +google-scholar: true +fileClass: authored +bibliography: + - background.bib +citation-style: springer-humanities-brackets +format: + html: + embed-resources: true + link-external-icon: true # externe links markieren + link-external-newwindow: true # externe linkn in neuem Fenster öffnen + toc-location: left # table of contents links (oder rechts) + toc: true + citation-location: document + reference-location: margin # fußnoten im Margin (falls gewünscht) + mermaid: + theme: default + theme: + - themes/nfdi.scss # theme aus ./themes/ auswählen +--- + +## 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. + +[Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien +[@prlic2012ten; @wilson2017good; @katz2021open; +@endings2020principles].]{.aside} + +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 +insbesondere die Prinzipien des _Endings-Projekts_ für digitale Langlebigkeit +[@endings2020principles]. 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. 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**. 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. +Beispiel: _“Dieses Tool extrahiert Personen-Netzwerke aus historischen +Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”_ 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). + +### 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 in einem _statischen Dokument_ +festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie +die Software die Daten interpretiert. Eine Tabelle oder Auflistung der +Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht die Klarheit. +[Beispiel: _“Eingabedatei: CSV mit Spalten `Autor`, `Empfänger`, ...; Ausgabe: +JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”_]{.aside} + +### Code-Abhängigkeiten und technische Voraussetzungen + +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”_). [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.]{.aside} + +- **Typische Nutzungsszenarien und Workflows:** Zeigen Sie anhand von + _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 + (_“Getting Started”_-Abschnitt). Beschreiben 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”_). Diese Beispiele sollten + realistisch und möglichst _repräsentativ für wissenschaftliche Anwendungen_ + sein. Nutzen Sie gerne kleine 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). + [Faustregel: **Zeigen statt nur beschreiben** – konkrete Anwendungsfälle in + der Doku verankern.]{.aside} + +### Wissenschaftlicher Hintergrund und theoretischer Kontext + +Da es sich um Forschungssoftware handelt, sollten Sie den _wissenschaftlichen +Kontext_ offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, +Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in +Überblicksform. Verweisen Sie auf _relevante Publikationen_ oder Theorien, damit +andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: +_“Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur +Netzwerkanalyse historischer Korrespondenz.”_ Halten Sie diesen Abschnitt aber +prägnant – Details gehören in die Forschungsarbeit selbst. Wichtig 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. [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).]{.aside} + +### Bekannte Limitationen, Annahmen und Fehlermeldungen + +Geben Sie ehrlich Auskunft über die _Grenzen der Software_. Welche Fälle werden +**nicht** abgedeckt? Welche Annahmen über die Daten oder Anwendungsszenarien +werden getroffen? Dokumentieren Sie bekannte Probleme oder Einschränkungen +(z. B. _“funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 +Mio. Datensätze, da Speicherbegrenzung”_). Solche Hinweise verhindern +Fehlanwendungen und sparen Nutzern Zeit. Falls es bekannte **Bugs oder +Workarounds** gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem +Abschnitt "Bekannte Probleme") erwähnt werden. Eine transparente Auflistung von +Limitationen erhöht die Vertrauenswürdigkeit und hilft anderen, die Ergebnisse +richtig einzuordnen. Auch **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 wie es +behoben werden kann (z. B. _“Fehler: Ungültiges Datum im Feld XY – bitte Format +TT/MM/JJJJ verwenden.”_). Solche in den Code integrierten Hinweise ergänzen die +schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei. + +### Weiterentwicklung und Beitragsmöglichkeiten + +Obwohl 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 +Autor (E-Mail) gehört dazu. Ebenso können **Community Guidelines** skizziert +werden: etwa Codierstandards 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…”_. [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.]{.aside} + +### Projekt-Metadaten (Lizenz, Zitation, Version) + +Teil der Dokumentation sind auch formale Informationen, die im Repository leicht +zugänglich sein sollten. **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[@smith2016software]. Schließlich +ist es sinnvoll, eine **Versionsnummer** der Software zu nennen (idealerweise in +README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die +Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen +gibt. Diese Praxis entspricht auch den ENDINGS-Prinzipien, die verlangen, dass +jede veröffentlichte Version eindeutig erkennbar ist und zitiert werden kann. + +### Zusammenfassung der inhaltlichen Anforderungen + +Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten: _Was_ +tut die Software, _warum_ wurde sie geschrieben (wissenschaftlicher Zweck), +_wer_ soll sie nutzen, _wie_ wird sie benutzt (Inputs, Outputs, Abläufe), +_womit_ läuft sie (Umgebung/Abhängigkeiten), _unter welchen Bedingungen_ +(Annahmen/Limitationen) und _wohin_ können sich Nutzer wenden +(Support/Zitation). All diese Punkte sorgen für **Nachvollziehbarkeit** (im +Sinne von Reproduzierbarkeit der Ergebnisse) und **Weiterverwendbarkeit** (im +Sinne von Adaptierbarkeit der Software für neue Kontexte). + +## Format und Struktur der Dokumentation + +Für Forschende ohne viel Ressourcen muss die Dokumentation **einfach zugänglich, +leicht pflegbar und ohne Spezialsoftware** erstellbar sein. Daher empfiehlt es +sich, auf **leichte Formate** und eine klare Struktur zu setzen: + +### `README.md` als zentrales Dokument + +Die Hauptdokumentation sollte als README in Markdown-Format im Hauptverzeichnis +des Code-Repositoriums liegen. Dieses README fungiert als “Startseite” des +Projekts und enthält idealerweise eine komprimierte Übersicht aller wichtigen +Punkte: Zweck der Software, Kurzbeschreibung, Installation, kurzer +Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie GitHub, GitLab etc. wird +die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die Vorteile von +**Markdown** sind die einfache Lesbarkeit in Rohform, die breite Unterstützung +(auch in Renderern wie GitHub-Webansicht) und die Eignung für Versionierung +(Textdatei im Git). So bleibt die Dokumentation eng mit dem Code verzahnt und +unter Versionskontrolle – ein Prinzip, das auch von ENDINGS propagiert wird +(Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden). + +### Strukturierte Unterteilung in weitere Dateien/Abschnitte + +::: {.column-margin} + +```plain +example-project/ +├── README.md +├── CONTRIBUTING.md (optional) +├── CHANGELOG.md (optional) +├── CITATION.md (oder CITATION.cff) +├── LICENSE +├── data/ (optional) +│ └── sample_data.csv +├── docs/ (optional) +│ ├── INSTALL.md +│ └── USAGE.md +├── examples/ (optional) +│ └── example_workflow.ipynb +└── src/ + ├── script.py + └── module/ + └── helper.py +``` + +Beispielhafter Struktur eines Code-Repositories + +::: + +Sollte die Dokumentation umfangreicher sein, ist es sinnvoll, sie in logisch +getrennte Abschnitte aufzuteilen. Dies kann innerhalb der README durch +Überschriften geschehen oder durch **zusätzliche Markdown-Dateien** im +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.: + +- `README.md` – Überblick (Ziel, Installation, kurzes Beispiel, Lizenz/Zitation) +- `docs/` Verzeichnis mit weiteren .md-Dateien für tiefergehende Dokumentation + (optional) +- `CONTRIBUTING.md` – Hinweise für Beiträger (falls relevant) +- `LICENSE` – Lizenztext +- `CITATION.cff` oder `CITATION.md` – wie zu zitieren. + +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. + +### Keine proprietären Formate oder Abhängigkeit von Werkzeugen + +Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten, +sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown, +reStructuredText). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente +oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht +diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil +des Versionskontrollsystems. Ein Markdown-Dokument hingegen kann gemeinsam mit +dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Zudem +erlauben offene Formate eine leichtere **Langzeitarchivierung**: Gemäß +Endings-Prinzip sollten Informationsressourcen in langfristig lesbaren Formaten +vorliegen. Markdown/Plaintext erfüllt diese Bedingung (im Gegensatz etwa zu +einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 +Jahren evtl. nicht mehr läuft). Im Sinne der _Digital Longevity_ ist eine +**statische HTML- oder PDF-Version** der Dokumentation (automatisch generiert +aus Markdown) als Teil der Release-Artefakte sinnvoll – so kann z. B. in jeder +veröffentlichten Version ein PDF-Handbuch beigelegt werden, das später zitiert +oder referenziert werden kann. **Wichtig ist aber, dass die Quelle der Wahrheit +immer die im Repository gepflegte Doku bleibt.** + +### Übersichtlichkeit und Navigierbarkeit + +Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit +Leser schnell die gesuchten Informationen finden. Eine **logische Gliederung** +(wie in diesem Katalog: Einführung, Anforderungen, Installation, Nutzung, +Hintergrund, etc.) hilft unterschiedlichen Nutzergruppen gezielt das Relevante +zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine +Abschnittsübersicht am Anfang nützlich sein. Markdown bietet z. B. automatische +Toc-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur +zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an +einem Ort). Wiederholungen sollten vermieden werden: lieber an einer Stelle +ausführlich dokumentieren und sonst darauf verweisen, um Konsistenzprobleme zu +vermeiden (_"Don’t Repeat Yourself"_ gilt auch für Dokumentation). Bei ähnlichen +Projekten können Sie sich an bestehenden **Dokumentationsvorlagen** orientieren: +Viele erfolgreiche Open-Source-Projekte haben auf GitHub eine ähnliche +README-Struktur, die als informelles Template dienen kann. + +### 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. + +### Fazit Format und Struktur + +Insgesamt gilt: **Die Dokumentation sollte im gleichen Repository leben wie der +Code, klar strukturiert und in einem einfach handhabbaren Format vorliegen.** +Sie soll ohne spezielle Umgebung lesbar sein – ein Nutzer, der das Repository +klont oder herunterlädt, muss sofort Zugang zur Dokumentation haben. Dieses +Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software +(und deren Doku) _auffindbar_ und _zugänglich_ zu machen, ohne Hürden. Eine gut +gepflegte README in Markdown erfüllt diese Anforderungen in den meisten Fällen +optimal. + +## Umfang und Fokus der Dokumentation + +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. + +## (Teil-)automatisierte Dokumentationswerkzeuge + +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: + +### Docstrings und API-Dokumentationsgeneratoren + +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. + +::: {.column-margin} + +Ä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. + +### Jupyter Notebooks und literate programming + +Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind +**Jupyter Notebooks** bzw. R Markdown Notebooks [@maria2019jupyter]. Diese +erlauben es, _ausführbaren Code mit erklärendem Text und Visualisierungen_ in +einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei +leisten: (1) als **Tutorials/Beispiel-Workflows**, die Nutzer interaktiv +nachvollziehen können, und (2) als **Reproduzierbarkeits-Dokumentation** für +analytische Prozesse. Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist, +könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall +durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der +Ergebnisse). + +Notebooks senken die Hürde, weil Nutzer direkt experimentieren können, und +fördern transparente Forschung, da Code, Ergebnisse und Beschreibung +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. + +::: {.callout-warning} + +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. + +### Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten) + +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. [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.]{.aside} + +**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. + +### In-Code Hilfefunktionen und CL-Interface Doku + +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. + +### Versionskontrolle und kontinuierliche Dokumentationspflege + +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.]{.aside} + +### Spezialfälle + +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. + +### Wann ist was verpflichtend + +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. + +## Best Practices, Vorlagen und Checklisten + +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: + +### Orientierung an Nutzerbedürfnissen + +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. + +### Checkliste für die Mindest-Dokumentation + +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: + +1. **Zielklärung:** Ist der Zweck der Software klar benannt und der + wissenschaftliche _Need_ begründet? (Falls nein, ergänzen: _Warum existiert + dieses Tool?_) +2. **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)? +3. **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? +4. **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? +5. **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. +6. **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. +7. **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? +8. **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. +9. **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. +10. **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. + +### Positiv- und Negativbeispiele studieren + +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. + +### Prinzipien: FAIR und ENDINGS + +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. + +### Kontinuierliche Verbesserung und Feedback + +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. + +### Zusammenfassung Best Practices + +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. + +## 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. + +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**. + +### Tabellarische Übersicht der Dokumentations-Bestandteile + +::: {.column-page-right} + +Table: _Empfohlene Dokumentationselemente, Inhalte und Umfang._ Diese Übersicht +kann als Vorlage dienen, welche Komponenten ein Dokumentationspaket enthalten +sollte. Je nach Projekt können einige Elemente wegfallen oder kombiniert werden +– entscheidend ist, dass die Kerninformationen (siehe oben) nicht fehlen. + +| **Dokuelement** | **Inhalt/Purpose** | **Format/Ort** | **Umfang** | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------- | +| **README (Hauptdoku)** | Zweck der Software; Kurzbeschreibung; Installationsanleitung; einfaches Nutzungsbeispiel; Lizenz- und Kontaktinfo | Markdown im Root des Repos (statisch versioniert) | 1–2 Seiten | +| **Eingabe/Ausgabe-Guide** | Beschreibung der erwarteten Inputs (Datenformat, Parameter) und generierten Outputs (Dateien, Berichte) inkl. Beispielen | Teil der README oder separate Datei (z.B. USAGE.md) | 1 Seite (mit Beispielen) | +| **Wissenschaftlicher Hintergrund** | Erläuterung der Methode, Theorie, Algorithmen; Verweise auf Literatur | README-Abschnitt "Hintergrund" oder separate Doku (BACKGROUND.md) | 0.5–1 Seite (plus Referenzen) | +| **Bekannte Limitationen** | Auflistung von Einschränkungen, Annahmen, bekannten Problemen; ggf. Workarounds | README-Abschnitt "Limitations" oder FAQ.md | 0.5 Seite | +| **Beispiel-Workflow (Tutorial)** | Schritt-für-Schritt Anleitung mit einem realistischen Anwendungsfall (ggf. mit Code und Screenshot) | Jupyter Notebook (`.ipynb`) im Repo `examples/` Ordner oder Markdown in docs/ | 1–3 Seiten / entsprechend Zellen | +| **API-Referenz** | Technische Dokumentation von Funktionen/Klassen für Entwickler\*innen | Automatisch generiert aus Docstrings (z.B. Sphinx in `docs/` Ordner, HTML/PDF Ausgabe) | Je nach Codegröße (ggf. umfangreich) | +| **CONTRIBUTING** | Anleitung für Beitragswillige: Code Style, Workflow, Tests, Kontakt | CONTRIBUTING.md im Repo | 0.5–1 Seite | +| **LICENSE** / **CITATION** | Rechtliche Infos (Lizenztext); Zitationsleitfaden (Bevorzugte Zitierweise, DOI) | Jeweils eigene Datei im Repo (Plain Text/Markdown) | Kurz (Standardtext bzw. Referenz) | +| **Release-Information** | Versionshinweise, Änderungsprotokoll (Changelog) | CHANGELOG.md oder Releases auf GitHub | fortlaufend pro Version (Stichpunkte) | + +::: + +### Schlusswort + +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. diff --git a/background/background.bib b/background/background.bib new file mode 100644 index 0000000..5a18543 --- /dev/null +++ b/background/background.bib @@ -0,0 +1,69 @@ +@article{wilson2017good, + title={Good enough practices in scientific computing}, + author={Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K}, + journal={PLoS computational biology}, + volume={13}, + number={6}, + pages={e1005510}, + year={2017}, + publisher={Public Library of Science} +} + +@article{prlic2012ten, + title={Ten simple rules for documenting scientific software}, + author={Prli{\'c}, Andreas and Procter, James B}, + journal={PLoS Computational Biology}, + volume={8}, + number={12}, + pages={e1002802}, + year={2012}, + publisher={Public Library of Science} +} + +@article{smith2016software, + title={Software citation principles}, + author={Smith, Arfon M and Katz, Daniel S and Niemeyer, Kyle E and FORCE11 Software Citation Working Group and others}, + journal={PeerJ Computer Science}, + volume={2}, + pages={e86}, + year={2016}, + publisher={PeerJ Inc.} +} + +@article{maria2019jupyter, + title={Jupyter notebooks—a publishing format for reproducible computational workflows}, + author={Kluyver, Thomas and Ragan-Kelley, Benjamin and P{\'e}rez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica B and Grout, Jason and Corlay, Sylvain and others}, + journal={Positioning and Power in Academic Publishing: Players, Agents and Agendas}, + volume={20}, + pages={87--90}, + year={2016}, + publisher={IOS Press} +} + +@misc{endings2020principles, + title = {Endings Principles for Digital Longevity}, + author = {{Endings Project}}, + year = {2020}, + url = {https://endings.uvic.ca/principles.html} +} + +@article{katz2021open, + title={The Journal of Open Source Software (JOSS)}, + author={Katz, Daniel S and Niemeyer, Kyle E and Smith, Arfon M}, + journal={PeerJ Computer Science}, + volume={7}, + pages={e432}, + year={2021}, + publisher={PeerJ Inc.} +} + +@article{lamprecht2020towards, + title={Towards FAIR principles for research software}, + author={Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and others}, + journal={Data Science}, + volume={3}, + number={1}, + pages={37--59}, + year={2020}, + publisher={IOS Press} +} diff --git a/background/springer-humanities-brackets.csl b/background/springer-humanities-brackets.csl new file mode 100644 index 0000000..1f4d567 --- /dev/null +++ b/background/springer-humanities-brackets.csl @@ -0,0 +1,421 @@ + + diff --git a/background/themes/nfdi.scss b/background/themes/nfdi.scss new file mode 100644 index 0000000..1d1167e --- /dev/null +++ b/background/themes/nfdi.scss @@ -0,0 +1,119 @@ +/*-- scss:defaults --*/ + // --primary-color: light-dark(#006890,#004f6e); + + +$blue: #004f6e !default; +$blue-light: #006890 !default; +// $indigo: #6610f2 !default; +$purple: #7e3f73 !default; +// $pink: #d63384 !default; +$red: #c44814 !default; +// $orange: #fd7e14 !default; +$yellow: #deae00 !default; +$green: #7ba01e !default; +// $teal: #20c997 !default; +$cyan: #008ac0 !default; +$gray: #9d9d9d !default; + +$white: #fff !default; +$gray-100: tint-color($gray, 80%) !default; +$gray-200: tint-color($gray, 60%) !default; +$gray-300: tint-color($gray, 40%) !default; +$gray-400: tint-color($gray, 20%) !default; +$gray-500: $gray !default; +$gray-600: shade-color($gray, 20%) !default; +$gray-700: shade-color($gray, 40%) !default; +$gray-800: shade-color($gray, 60%) !default; +$gray-900: shade-color($gray, 80%) !default; +$black: #000 !default; + +$primary: $blue !default; +$secondary: $blue-light !default; +$accent: $yellow !default; +$success: $green !default; +$info: $cyan !default; +$warning: $yellow !default; +$danger: $red !default; +$light: $gray-100 !default; +$dark: $gray-900 !default; + +$min-contrast-ratio: 2.6 !default; + +$link-color: $secondary !default; +// Options + +$enable-rounded: true !default; + +// Body + +$body-color: $gray-800 !default; + +// Fonts + +// stylelint-disable-next-line value-keyword-case +//$font-family-sans-serif: "Source Sans Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default; +$headings-font-weight: 400 !default; + +// Navbar + +$navbar-dark-hover-color: rgba($white, 1) !default; +$navbar-light-hover-color: rgba($black, .9) !default; + +// Alerts + +$alert-border-width: 0 !default; + +// Progress bars + +$progress-height: .5rem !default; + + +/*-- scss:rules --*/ + + +// Variables + +// $web-font-path: "https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@300;400;700&display=swap" !default; +// @if $web-font-path { +// @import url($web-font-path); +// } + +// Typography + +body { + -webkit-font-smoothing: antialiased; +} + +// Indicators + +.badge { + &.bg-light { + color: $dark; + } +} + +// Progress bars + +.progress { + @include box-shadow(none); + + .progress-bar { + font-size: 8px; + line-height: 8px; + } +} + + +h1, h2, h3, h4, h5, h6 { + color: $primary; +} + + +strong { + text-shadow: 0px 0px 1px $secondary; +} + +em { + text-shadow: 0px 0px 1px $secondary; +} +