quarto/Writing/documentation.md

---
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
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"
date: 2025-05-08
categories:
  - Article
  - Best Practices
citation: true
google-scholar: true
fileClass: authored
bibliography:
  - documentation.bib
image: ../thumbs/writing_documentation.png
---

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

## Methodik / LLMs als 'Autoren' {.appendix}

Erstellt wurde der initial draft mittels Websuche und "Deep-Research" von
`gpt-4.5 (preview)`. Abschließendes Korrekturlesen/inhaltliche Prüfung/Layouting
durch Nicole Dresselhaus.