doc_documentation/background/BACKGROUND.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
date: 2025-06-05
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
      - Investigation
      - Supervision
      - Validation
      - "Writing – review & editing"
  - name: GPT-4.5 "deep research"
    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:
    css: extra-styles.css
    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.

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
[@Hasselbring2020OpenSourceResearch; @Lee2018Tensimplerules] und damit
einhergehender Prinzipien wie die des _Endings-Projekts_ für digitale
Langlebigkeit [@EndingsPrinciples221] und
_FAIR4RS-Prinzipien_[@BarkerEtAl2022IntroducingFAIR].

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[@Wilson2017GoodEnoughPractices].

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**[@EndingsPrinciples221;
@Lamprecht2020TowardsFAIRPrinciples, R1]. 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.”_]{.aside}
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 auch in einem _statischen
Dokument_ festgehalten und der Software beigelegt sein – so bleibt
nachvollziehbar, wie die Software die Daten interpretiert
[@EndingsPrinciples221]. 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}

Gerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation
via [JSON-Schema](https://json-schema.org/draft/2020-12/json-schema-core) an.

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

### Wissenschaftlicher Hintergrund und theoretischer Kontext

Da es sich um Forschungssoftware handelt, sollten Sie den _wissenschaftlichen
Kontext_ ^[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).] 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.”_]{.aside} 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.

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

[Beispielsweise: _“funktioniert nur für Deutschsprachige Texte”_ oder _“maximale
Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”_]{.aside} 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.

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 bestenfalls direkt wie
es behoben werden kann. [Beispiel: _“Fehler: Ungültiges Datum im Feld XY – bitte
Format TT/MM/JJJJ verwenden.”_]{.aside} 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\*zur Autor\*in (E-Mail) gehört dazu.

Ebenso können **Community Guidelines** skizziert werden: etwa Code-Standards
oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte
reicht oft ein Satz wie _“Beiträge durch Pull Requests sind willkommen; bei
Fragen wenden Sie sich an…”_. ^[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[@Lamprecht2020TowardsFAIRPrinciples].
**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 [@Smith2016SoftwareCitationPrinciples].

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[@EndingsPrinciples221].

### Zusammenfassung der inhaltlichen Anforderungen

::: {.callout-important title="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.

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

### Keine proprietären Formate oder Abhängigkeit von Werkzeugen

::: {.callout-tip .column-margin title="Prinzip"}

Dokumentation gehört zum Code und muss auch ohne Programm lesbar sein.

:::

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][rst]).

[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.]{.bad-practice} Ein [Markdown][]-Dokument hingegen kann
gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent
nachvollziehbar.

Im Sinne der _Digital Longevity_[@EndingsPrinciples221] ist eine **statische
HTML- oder PDF-Version** der Dokumentation (automatisch generiert aus
[Markdown][] via [pandoc][]) als Teil der Release-Artefakte sinnvoll. **Wichtig
ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku
bleibt.**

### Strukturierte Unterteilung in weitere Dateien/Abschnitte

::: {.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 wie oben benannt sein, damit sie
leicht auffindbar und ggf. direkt durch Tools verarbeitbar sind.

### Übersichtlichkeit und Navigierbarkeit

::: {.callout-tip .column-margin title="Prinzip"}

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

:::

Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit
Leser schnell die gesuchten Informationen finden. Eine **logische Gliederung**
hilft unterschiedlichen Nutzergruppen gezielt das Relevante zu finden. Für
längere Dokumente kann ein Inhaltsverzeichnis oder eine Abschnittsübersicht am
Anfang nützlich sein. [Markdown][] bietet z. B. automatische TOC-Generierung auf
manchen Plattformen.

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

### Beispiele, Codeblöcke und ggf. Abbildungen einbinden

::: {.callout-tip .column-margin title="Prinzip"}

Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.

:::

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.

::: {.callout-note title="Typische Nutzungsszenarien und Workflows"
collapse="true"}

Zeigen Sie anhand von _konkreten Beispielen_, wie die Software benutzt wird. Ein
**Quickstart-Beispiel** senkt die Einstiegshürde enorm. Dies kann z. B. eine
Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum
gewünschten Ergebnis kommt.

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, mitgelieferte
Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt
ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen
Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei
Kommandozeilentools, via `--help` dokumentiert).

:::

### Umfang und Fokus der Dokumentation

::: {.callout-tip .column-margin title="Prinzip"}

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 oder mehr als 1 Stunde immer noch
  nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.

:::

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

::: {.bad-practice}

Negativbeispiele umfassen:

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

:::

Halten Sie auch die Sprache prägnant:

- kurze Absätze
- Listen
- und einfache Sätze

erhöhen die Lesbarkeit.

**Fachtermini** aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet
werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht
kennen.

#### Fokus auf Nutzer\*innen - nicht Entwickler\*innen

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

_Forschende_ fragen:

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

_Entwicklende Personen_ fragen:

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

Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf
Zweck, Nutzung und Ergebnisse. Konzentrieren Sie die Hauptdokumentation darauf,
**das Nutzen und Verstehen der Software von außen** zu ermöglichen.

### Priorisierung bei Zeitmangel

Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für
die Autoren selbst, wenn sie das Tool später wieder anfassen).
Entwickler\*innendokumentation (z. B. detaillierte API-Dokumente,
Code-Kommentare, technische Architektur) kann separat gehalten werden, oder
sogar automatisch erzeugt werden.

#### Minimaldokumentation: kurze Kommentare

Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt
(_“keine Dokumentation”_ ist keine Option). _Good Enough
Practices_[@Wilson2017GoodEnoughPractices] empfehlen, als ersten Schritt
zumindest einen **kurzen erklärenden Kommentar am Anfang jedes Scripts** oder
eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt
bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert.
Später kann die Dokumentation erweitert werden, insbesondere wenn die Software
in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass
ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B.
durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst _klein_
anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen
sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte
30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).

#### Verlinkte Dokumentation ist auch Dokumentation

Nutzen Sie **Verweise und vorhandene Ressourcen**. Wenn z. B. Ihr Tool auf einem
komplizierten Setup (Datenbank, Webserver) aufbaut, brauchen Sie nicht jede
Installationsoption im Detail in Ihrer Doku zu reproduzieren – verlinken Sie auf
offizielle Installationsanleitungen dieser Abhängigkeiten, und nennen Sie nur
Ihre spezifischen Konfigurationen und verlinken sie auf die Dokumentation des
Setup-Elementes für alles weitere. Ebenso können Tutorials oder Papers, die
schon existieren, als weiterführende Links angegeben werden, anstatt Inhalte
redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.

#### Und anschließend?

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

## Was macht eine gute Dokumentation aus

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

Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
**FAIR4RS-[@BarkerEtAl2022IntroducingFAIR]** bzw.
**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.

::: {.callout-note .column-margin title="FAIR4RS-Prinzipien für Software"}

Die FAIR4RS-Prinzipien sind eine Anpassung der Ursprünglich nur für Daten
gedachten FAIR-Prinzipien. Der Fokus liegt hier nicht auf Software selbst,
sondern auf eine Nutzung von Software die ein Äquivalent zur Nutzung von
FAIR-Daten darstellt.

:::

::: {.callout-note .column-margin title="ENDINGS-Prinzipien"}

Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung
von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und
Zitierbarkeit.

:::

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

- Reproduzierbarkeit (Installation, Daten, Beispiele),
- Offenheit (Lizenz, offene Formate) und
- Nachhaltigkeit (Versionierung, Langlebigkeit der Doku).

Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie
automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche
Softwarepraxis.

### Nutzungshilfen außerhalb der Dokumentation

Falls Ihre Software ein **Command-Line Interface (CLI)** hat, stellen Sie
sicher, dass eine eingebaute Hilfe vorhanden ist (z. B. Ausgabe bei `--help`).
Viele Nutzer greifen zunächst darauf zurück. Dieses Hilfemenü sollte kurz
erläutern, welche Subkommandos oder Optionen existieren. Moderne CLI-Frameworks
generieren solche Hilfen oft automatisch aus Ihrem Code (z. B. [argparse][] in
Python erzeugen `--help`-Texte). Nutzen Sie das, um konsistente Infos zu
garantieren.

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.

### Kontinuierliche Verbesserung und Feedback

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

- früh Feedback von Testnutzer\*innen oder Kolleg\*innen einzuholen: Lassen Sie
  jemanden die Anleitung befolgen und hören Sie auf Stolpersteine. Oft zeigen
  sich Lücken erst im Praxistest ("Ich wusste nicht, was ich nach Schritt X tun
  soll" etc.).
- Planen Sie Zeiten ein, die Dokumentation nachzuführen, insbesondere wenn sich
  die Software ändert. Ein lebendiges Projekt wird vielleicht Release für
  Release die Dokumentation erweitern (evtl. neue Tutorials, neue Module
  dokumentieren). Spätestens zum Release-Zeitpunkt sollten diese auffallen und
  ggf. als Issues adressiert werden.
- 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.

### Positiv- und Negativbeispiele studieren

Schlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist
ein Blick auf Projekte mit exzellenter Doku. Im _[Journal of Open Source
Software (JOSS)][JOSS]_ werden z.B. Softwareartikel veröffentlicht, bei denen
die zugehörigen Repositorien aufgrund des
[Review-Prozesses](https://joss.readthedocs.io/en/latest/review_checklist.html)
vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.

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.

## (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:

### Jupyter Notebooks und literate programming

Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind
**Jupyter Notebooks** bzw. **R Markdown Notebooks**
[@KluyverEtAl2016JupyterNotebookspublishing]. 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 title="Vorsicht bei Python-Notebooks"}

Notebooks erfordern eine lauffähige Umgebung – das heißt, Sie müssen darauf
achten, dass alle Abhängigkeiten im Notebook deklariert sind oder ggf.
nachinstalliert werden und die Daten zugänglich sind.

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

Deshalb: Wenn Sie Notebooks als Doku nutzen, stellen Sie sicher, dass sie
_leicht ausführbar_ sind (z. B. durch Bereitstellen von Umgebungsdateien wie
`environment.yml` oder Dockerfiles, kleinen Beispieldatensätzen und klaren
Anweisungen im Notebook). Ggf. kann man zusätzlich auch reine
Markdown/HTML-Exporte von evaluierten Notebooks exportieren und dem Repo
beilegen, damit zumindest statisch die Inhalte einsehbar sind.

:::

#### Wann sollten Sie Notebooks nutzen?

Notebooks sind quasi Goldstandard, um wissenschaftliche Analysen nachvollziehbar
zu machen. In Projekten, wo es um Data Science Workflows oder interaktive
Exploration geht, sollten Notebooks stark erwogen werden, während für ein reines
Tool/Script eine gut geschriebene README mit Beispielausgabe ausreichend sein
kann.

### Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)

::: {.callout-tip .column-margin title="Prinzip"}

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

:::

Für umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll
sein, eine **Dokumentationswebsite** zu generieren. Tools wie _[Sphinx][]_
(zusammen mit ReadTheDocs für Hosting) oder _[MkDocs][]_ erlauben es, aus
[Markdown][]/[reStructuredText][rst]-Dateien einen ansprechend formatierten
HTML-Dokumentationssatz zu bauen. Der Vorteil ist, dass man eine durchsuchbare,
verlinkte Doku bekommt, oft mit schönem Layout und zusätzlicher Navigation. Mit
_Continuous Integration_ lassen sich diese Seiten bei jedem Git-Push automatisch
aktualisieren.

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

Solche Tools sind **sinnvoll, wenn die Dokumentation sehr groß oder öffentlich
weit verbreitet** ist – z. B. wenn Ihre Software von vielen genutzt wird und Sie
ein professionelles Auftreten wünschen, oder wenn Sie die Doku als PDF
veröffentlichen möchten. [In kleinen DH-Projekten ist es oft nicht nötig, extra
eine Webseite zu hosten; dennoch kann Sphinx auch lokal HTML/PDF erzeugen, was
man dem Repo beilegen kann.]{.aside}

#### Wann sollten Sie eine statische Website generieren?

**Verpflichtend** ist so ein Tool selten, höchstens wenn Förderprogramme oder
Journals ein dokumentationsseitiges HTML-Manual verlangen. Wenn Sie jedoch
planen, Ihre Software z. B. über Jahre zu pflegen und ggf. einem Journal wie
JOSS vorzustellen, dann erwartet die Community meist, dass zumindest eine
Sphinx/Doxygen-Doku für die API (s.u.) existiert.

### Docstrings und API-Dokumentationsgeneratoren

::: {.callout-tip .column-margin title="Prinzip"}

Benutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die
Software aber woanders eingebunden, ist dieses notwendig. Generation dieser
Dokumentation ist daher der beste Weg.

:::

Nutzen Sie die Möglichkeit, Dokumentation _direkt im Quellcode_ unterzubringen,
z. B. in Form von **Docstrings^[kurz für: "Documentation String"]** (mehrzeilige
Strings in Funktionen/Klassen bei Python, [Roxygen][]-Kommentare in R,
[Javadoc][]-Kommentare in Java, etc.).

Diese dienen doppelt: Zum einen erleichtern sie es Ihnen und Kollegen, den Code
beim Lesen zu verstehen, zum anderen können sie von Tools ausgelesen und zu
hübschen API-Dokumentationen verarbeitet werden. Idealerweise dokumentieren Sie
_jede wichtige **oder** von außen sichtbare Funktion, Klasse oder Modul_ mit
einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele
enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.

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

Mit Tools, wie **[Sphinx][]**, **[Javadoc][]**, **[Doxygen][]**,
**[MkDocs][]**,**[pdoc][]** und vielen weiteren, können aus Docstrings
automatisiert Webseiten oder PDF-Handbücher generiert werden. Sie lesen z. B.
die Python-Docstrings und erzeuge daraus strukturiert eine Dokumentation; Häufig
kann über Erweiterungen auch dritte Dokumentation direkt eingebunden und
verlinkt werden.

### Versionskontrolle und kontinuierliche Dokumentationspflege

::: {.callout-tip .column-margin title="Prinzip"}

Die beste Dokumentation ist die, die sich selbst aktualisiert.

:::

Eine Form der _Teil-Automatisierung_ ist es, die Dokumentation an den
Entwicklungs-Workflow zu koppeln. So sollte die Dokumentation im selben
Versionskontrollsystem (Git) liegen wie der Code, damit Änderungen synchron
nachverfolgt werden. Es empfiehlt sich, bei jedem größeren Code-Update zu
prüfen, ob die Doku noch stimmt (das kann man sich z. B. als Punkt in
Pull-Request-Reviews notieren oder per Issue-Template abfragen). Für Projekte
mit Continuous Integration (CI) kann man sogar automatisierte Checks einrichten,
die z. B. prüfen, ob die Doku gebaut werden kann oder ob Docstrings fehlen.
Einige CI-Skripte generieren bei jedem Commit eine frische Doku (z. B. mittels
Sphinx) und veröffentlichen sie – so ist garantiert, dass _die aktuelle
Codeversion immer eine aktuelle Doku hat_.

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

## Checklisten und Vorlagen

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.

### 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](https://joss.readthedocs.io/en/latest/review_checklist.html),
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.**

### Implementierung aller Vorschläge als ready-to-use Repository

::: {.callout-important title="TODO"}

- [ ] Hier noch auf unsere Template-Repos verweisen.
- [ ] Template-Repos selbst ggf. automatisch auf Zenodo mit kleinem
      Erklärungstext veröffentlichen?

:::

## Fazit

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

Indem zentrale Inhalte (Ziele, Inputs/Outputs, Hintergrund, etc.) klar
dokumentiert, ein nutzerfreundliches Format (README im Repo) gewählt, der Umfang
fokussiert gehalten und hilfreiche Tools eingesetzt werden, kann die
Dokumentation zur Stärke eines Projekts werden statt einem lästigen Anhängsel.

So schließt sich der Kreis zwischen guter **Softwareentwicklung** und guter
**Wissenschaft**[@Forschungsgemeinschaft2025LeitlinienzurSicherung, Leitlinie
12]: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent
verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch
wie die Erfahrung zeigt, zahlen sich diese in Form von _Zeiteinsparung bei
Nutzern, höherer Zitierbarkeit und größerer Wirkung_ der Software aus. Mit
diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre
Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen –
trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: **Gut
dokumentierte Forschungscode ist nachhaltige Forschung**.

## Tabellarische Übersicht der Dokumentations-Bestandteile {.appendix .column-page}

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

:::

## Referenz Websites/Services {.appendix}

- [GitHub][]: Seite mit sehr vielen Open-Source-Projekten, die git verwenden.
  Gehört zu Microsoft
- [GitLab][]: Open-Source-Lösung für selbst gehostete Projektverwaltung (git,
  issue-tracking, …). Community (kostenfrei; limitierte features) oder
  Enterprise-Linzenz
- [JOSS][]: The Journal of Open Source Software is a developer friendly, open
  access journal for research software packages.
- [JORS][]: The Journal of Open Research Software features peer reviewed
  Software Metapapers describing research software with high reuse potential.

[GitHub]:
  https://github.com
  "Seite mit sehr vielen Open-Source-Projekten, die git verwenden. Gehört zu Microsoft"
[GitLab]:
  https://gitlab.com
  "Open-Source-Lösung für selbst gehostete Projektverwaltung (git, issue-tracking, …).
Community (kostenfrei; limitierte features) oder Enterprise-Linzenz"
[JOSS]: https://joss.theoj.org/ "The Journal of Open Source Software"
[JORS]:
  https://openresearchsoftware.metajnl.com/
  "The Journal of Open Research Software features peer reviewed Software Metapapers describing research software with high reuse potential."

## Referenz Software {.appendix}

- [argparse][]: Der Argument-Parser der Python-Standardbibliothek
- [Doxygen][]: Generator um aus C/C++ Docstrings eine Dokumentation zu
  generieren
- [git][]: Versionskontrollsystem
- [graphviz][]: Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf
  vielen Systemen verfügbar und rendert zu pdf/svg
- [Javadoc][]: Generator um aus Java Docstrings eine Dokumentation zu generieren
- [Markdown][]: Mittlerweile DER Standard bei plaintext-Dokumenten
- [mermaid.js][]: Sprache für Diagramme; kann automatisiert (z.b. durch pandoc,
  javascript im HTML, …) in Bilder gewandelt werden
- [MkDocs][]: Sehr einfacher und minimalistischer Generator für statische
  Websites aus Markdown
- [pandoc][]: DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln
  und hieraus HTML/PDF u.ä. erstellen
- [pdoc][]: Generator um aus Python Docstrings eine Dokumentation zu generieren
- [pylint][]: Linting-Tool für Python. Formatiert Code und weist auf Probleme
  (z.b. fehlende Dokumentation) hin.
- [Roxygen][]: Generator um aus R Docstrings eine Dokumentation zu generieren
- [rst][]: Alternative zu Markdown.
- [Sphinx][]: Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter
  readthedocs.com steht.

[argparse]:
  https://docs.python.org/3/library/argparse.html
  "Der Argument-Parser der Python-Standardbibliothek"
[Sphinx]:
  https://www.sphinx-doc.org
  "Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter
readthedocs.com steht."
[MkDocs]:
  https://www.mkdocs.org/
  "Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown"
[Doxygen]:
  https://www.doxygen.nl/
  "Generator um aus C/C++ Docstrings eine Dokumentation zu generieren"
[Roxygen]:
  https://roxygen2.r-lib.org/
  "Generator um aus R Docstrings eine Dokumentation zu generieren"
[Javadoc]:
  https://www.oracle.com/java/technologies/javase/javadoc.html
  "Generator um aus Java Docstrings eine
Dokumentation zu generieren"
[pdoc]:
  https://pdoc.dev/
  "Generator um aus Python Docstrings eine Dokumentation zu generieren"
[git]: https://git-scm.com "Das de-facto Standard-Versionskontrollsystem"
[graphviz]:
  https://graphviz.org/
  "Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg"
[Markdown]:
  https://en.wikipedia.org/wiki/Markdown
  "Mittlerweile DER Standard bei plaintext-Dokumenten"
[mermaid.js]:
  https://mermaid.js.org/
  "Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden"
[pandoc]:
  https://pandoc.org/MANUAL.html#pandocs-markdown
  "DER Konverter für Dokumente. Kann sehr viel in Markdown
wandeln und hieraus HTML/PDF u.ä. erstellen"
[pylint]:
  https://www.pylint.org/
  "Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation)
  hin."
[rst]: https://en.wikipedia.org/wiki/ReStructuredText "Alternative zu Markdown."

## Bibliographie {.appendix}