much more rework.

background/BACKGROUND.md

@@ -26,15 +26,16 @@ authors:
     roles:
       - Conceptualization
       - Supervision
+      - Investigation
       - Validation
       - "Writing – review & editing"
-  - name: GPT-4.5
+  - name: GPT-4.5 "deep research"
     url: https://chatgpt.com
     affiliation:
       - name: OpenAI
         url: https://openai.com
     roles:
-      - investigation
+      - Investigation
       - "Writing – original draft"
 citation: true
 google-scholar: true
@@ -44,6 +45,7 @@ bibliography:
 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
@@ -70,20 +72,20 @@ 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
-[@PrlicProcter2012TenSimpleRules; @WilsonEtAl2017Goodenoughpractices;
-@BarkerEtAl2022IntroducingFAIR; @EndingsPrinciples221].]{.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
-[@EndingsPrinciples221]. 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
+berücksichtigen Best Practices des Research Software Engineering (RSE) und damit
+einhergehender Prinzipien wie die des _Endings-Projekts_ für digitale
+Langlebigkeit [@EndingsPrinciples221] und _FAIR-Prinzipien_ für
+Software[@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[@WilsonEtAl2017Goodenoughpractices].
+
+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.
 
@@ -114,16 +116,23 @@ 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 [@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}
+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
 
@@ -141,6 +150,12 @@ _“Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation:
 bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder
 große Speicherkapazitäten – sind diese zu nennen.]{.aside}
 
+::: {.callout-tip title="Prinzip" .column-margin}
+
+Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.
+
+:::
+
 - **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
@@ -155,58 +170,62 @@ große Speicherkapazitäten – sind diese zu nennen.]{.aside}
   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).
-  [Prinpip 1: **Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der
-  Doku verankern.**]{.aside .principle}
 
 ### 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}
+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.”_ 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? 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.
+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.
+
+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 (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}
+_“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 Codierstandards
+oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte
+reicht oft ein Satz wie _“Beiträge durch Pull Requests sind willkommen; bei
+Fragen wenden Sie sich an…”_. ^[Dieser Aspekt muss nicht umfangreich sein, zeigt
+aber Offenheit und sorgt dafür, dass im Falle von Rückfragen die Hürde für
+Kontaktaufnahme niedrig ist.]
 
 ### Projekt-Metadaten (Lizenz, Zitation, Version)
 
@@ -216,50 +235,86 @@ 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
-[@SmithEtAl2016Softwarecitation]. 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.
+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 [@NoyEtAl2019IndustryscaleKnowledge].
+
+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
 
-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).
+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:
+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 – ein Prinzip, das auch von
-ENDINGS[@EndingsPrinciples221] propagiert wird (Dokumentation soll statisch und
-zusammen mit den Daten/Code abgelegt werden).
+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 title="Prinzip" .column-margin}
+
+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
 
@@ -303,44 +358,29 @@ Repository (z. B. eine `INSTALL.md` für ausführliche Installationshinweise,
 - `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][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. Ein [Markdown][]-Dokument hingegen kann
-gemeinsam mit dem Code gepflegt werden, und Änderungen sind transparent
-nachvollziehbar. Markdown/Plaintext erfüllt die Bedingung der offenen
-**Langzeitarchivierung**[@EndingsPrinciples221] (im Gegensatz etwa zu einer
-Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10 Jahren
-evtl. nicht mehr läuft). Im Sinne der _Digital Longevity_ ist eine **statische
-HTML- oder PDF-Version** der Dokumentation (automatisch generiert aus
-[Markdown][] via [pandoc][]) als Teil der Release-Artefakte sinnvoll. **Wichtig
-ist aber, dass die Quelle der Wahrheit immer die im Repository gepflegte Doku
-bleibt.**
+Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie
+leicht auffindbar sind.
 
 ### Übersichtlichkeit und Navigierbarkeit
 
+::: {.callout-tip title="Prinzip" .column-margin}
+
+_"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.
+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
 
@@ -348,15 +388,18 @@ 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.
+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
 
@@ -373,6 +416,13 @@ meisten Fällen optimal.
 
 ## Die Dokumentation selbst
 
+::: {.callout-tip title="Prinzip" .column-margin}
+
+Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen
+bringen und ein einfaches Beispiel ausführen?
+
+:::
+
 Gerade weil Forschende wenig Zeit haben, muss die Dokumentation **effizient**
 gestaltet sein – sie soll alle wichtigen Informationen enthalten, aber auch
 nicht unnötig ausschweifen. Für typische Forschungssoftware-Projekte in den
@@ -381,23 +431,27 @@ 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. [Prinzip 1: **Kann eine neue Person in < 1 Stunde mit
-Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel
-ausführen?**]{.aside .principle}
+lange, die nichts aussagt.
 
 ### Umfang und Fokus der Dokumentation
 
 Ein effizienter Umfang lässt sich erreichen, indem sie **alles, was für
 Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles
-andere skippen**. Negativbeispiele umfassen:
+andere skippen**.
+
+::: {.bad-practice}
+
+Negativbeispiele umfassen:
 
 - jeder interne Programmiertrick wird erläutert – Quellcode-Kommentare richten
-  sich an Entwickler, während die Nutzerdokumentation sich auf Nutzung und
-  Kontext beschränkt
+  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
@@ -430,9 +484,9 @@ eine Software weiter betrachten oder nicht, und hier zählt der erste Eindruck.
 
 Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für
 die Autoren selbst, wenn sie das Tool später wieder anfassen).
-Entwicklerdokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare,
-technische Architektur) kann separat gehalten werden, sofern nötig, um den
-Hauptnutzerfluss nicht zu überfrachten.
+Entwickler\*innendokumentation (z. B. detaillierte API-Dokumente,
+Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern
+nötig, um den Hauptnutzerfluss nicht zu überfrachten.
 
 #### Minimaldokumentation: kurze Kommentare
 
@@ -464,33 +518,33 @@ redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.
 #### Fokus auf Nutzer\*innen - nicht Entwickler\*innen
 
 Stellen Sie sich beim Schreiben der Doku die verschiedenen _Nutzerrollen_ vor:
-**“Zukünftiges Ich”**, **Kolleg\*innen**, **Fachforscher anderer Disziplin** und
-ggf. **Software-Entwickler, die den Code erweitern**. Jede dieser Gruppen möchte
-bestimmte Dinge wissen.
+**“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.
 
-_Forscher\*innen_ fragen:
+_Forschende_ fragen:
 
 - Was kann das Tool?
 - Wie benutze ich es?
 - In welchem Kontext steht es?
 
-_Entwickler\*innen_ fragen:
+_Entwicklende Personen_ fragen:
 
 - Wie kann ich beitragen?
 - Wie funktioniert es unter der Haube?
 
 Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf
-Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für Entwickler
-(z. B. Code-Struktur, To-do-Liste) können separat oder später ergänzt werden.
-Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwicklerdokus
-ohnehin nicht nötig – hier reicht es, den Code gut zu kommentieren und eventuell
-eine grobe Architekturübersicht bereitzustellen. Konzentrieren Sie die
-Hauptdokumentation darauf, **das Nutzen und Verstehen der Software von außen**
-zu ermöglichen.
+Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für
+Entwickler\*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später
+ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche
+Entwickler\*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code
+gut zu kommentieren und eventuell eine grobe Architekturübersicht
+bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, **das Nutzen
+und Verstehen der Software von außen** zu ermöglichen.
 
 #### Und anschließend?
 
-Wenn der Zeitmangel vorüber ist[^als ob DAS je der Fall wäre -.-], sollte man
+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
@@ -513,15 +567,20 @@ die Schwelle für alltägliche Fragen.
 ### Prinzipien: FAIR und ENDINGS
 
 Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
-**Research Software Engineering**[@citation-needed] und den
-**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht[Die ENDINGS-Prinzipien für
-digitale Projekte betonen insbesondere die Bedeutung von Dokumentation für
-Datenstrukturen, offenen Lizenzen, statischen Outputs und Zitierbarkeit. Unsere
-Empfehlungen, etwa ein statisches Markdown-README beizulegen, die
-Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu machen, setzen genau
-diese Vorgaben um. ]{.aside}.
+**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
+**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.
 
-Gute Dokumentation bedeutet daher u.a.
+::: {.callout-note title="ENDINGS-Prinzipien" .column-margin}
+
+Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung
+von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und
+Zitierbarkeit. Unsere Empfehlungen, etwa ein statisches Markdown-README
+beizulegen, die Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu
+machen, setzen genau diese Vorgaben um.
+
+:::
+
+Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von
 
 - Reproduzierbarkeit (Installation, Daten, Beispiele),
 - Offenheit (Lizenz, offene Formate) und
@@ -534,7 +593,7 @@ Softwarepraxis.
 ### Kontinuierliche Verbesserung und Feedback
 
 Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess.
-Best Practice sind daher insbesondere:
+Best Practice sind daher insbesondere:[@citation-needed]
 
 - früh Feedback von Testnutzer\*innen oder Kolleg\*innen einzuholen: Lassen Sie
   jemanden die Anleitung befolgen und hören Sie auf Stolpersteine. Oft zeigen
@@ -601,18 +660,21 @@ 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}
+::: {.callout-warning title="Vorsicht bei Python-Notebooks"}
 
-Notebooks erfordern allerdings eine lauffähige Umgebung – das heißt, Sie müssen
-darauf achten, dass alle Abhängigkeiten im Notebook deklariert sind und die
-Daten zugänglich sind. Es hat sich gezeigt, dass Notebooks aus Publikationen oft
-nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen
-fehlen. Deshalb: Wenn Sie Notebooks als Doku nutzen, stellen Sie sicher, dass
-sie _leicht ausführbar_ sind (z. B. durch Bereitstellen von Umgebungsdateien wie
+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 Notebooks auch in reine Markdown/HTML
-exportieren und dem Repo beilegen, damit zumindest statisch die Inhalte
-einsehbar sind.
+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.
 
 :::
 
@@ -626,6 +688,13 @@ kann.
 
 ### Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)
 
+::: {.callout-tip title="Prinzip" .column-margin}
+
+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
@@ -633,9 +702,7 @@ sein, eine **Dokumentationswebsite** zu generieren. Tools wie _[Sphinx][]_
 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. [Prinzip 2: **ab einer Codebasis `> einige tausend Zeilen` oder
-`>5 Module` lohnt es sich, eine generierte Dokumentation bereitzustellen, um
-(auch selbst) den Überblick zu behalten.**]{.aside .principle}
+aktualisieren.
 
 Für die Nachhaltigkeit ist wichtig, dass diese Webseiten statisch
 sind[@EndingsPrinciples221] – d.h. sie funktionieren ohne Server-Backends und
@@ -658,24 +725,30 @@ Sphinx/Doxygen-Doku für die API (s.u.) existiert.
 
 ### Docstrings und API-Dokumentationsgeneratoren
 
+::: {.callout-tip title="Prinzip" .column-margin}
+
+Benutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die
+Software aber woanders eingebunden, ist dieses notwendig.
+
+:::
+
 Nutzen Sie die Möglichkeit, Dokumentation _direkt im Quellcode_ unterzubringen,
-z. B. in Form von **[Docstrings][Docstring]** (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.[Prinzip 3: **Benutzt jemand die
-Software nur braucht es keine API-Dokumentationen; wird die Software aber
-woanders eingebunden ist dieses angeraten.**]{.aside .principle}
+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).
+Ökosystems (z. B. [Google Style Guide](https://google.github.io/styleguide/) für
+Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen).
 Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie
-etwa [pylint][], können die Verwendung erzwingen.
+etwa **[pylint][]**, können die Verwendung erzwingen.
 
 Mit Tools, wie **[Sphinx][]**, **[Javadoc][]**, **[Doxygen][]**,
 **[MkDocs][]**,**[pdoc][]** und vielen weiteren, können aus Docstrings
@@ -690,22 +763,13 @@ anderen genutzt werden soll, oder wenn das Projekt größer wird und die interne
 Struktur komplexer ist. In solchen Fällen kann eine _API-Referenz_ (automatisch
 aus dem Code erzeugt) eine erhebliche Hilfe sein.
 
-**Verpflichtend** wird dieser Ansatz etwa, wenn Sie ein Bibliothekspaket
-veröffentlichen (z. B. ein R-Package in CRAN oder Python-Package auf PyPI) –
-dort sind Docstrings und generierte Dokumentation quasi Standard. Für ein
-einmaliges Analyse-Skript in den Digital Humanities ist eine voll ausgebaute
-API-Doku vielleicht nicht nötig; hier reicht möglicherweise ein inline
-kommentierter Code. Häufig wandeln sich solche Analyse-Skripte aber über Zeit,
-sodass hier auch weitere Prinzipien guter Software[@citation-needed], wie
-Modularisierung empfohlen sind um gegebene Ansätze einfacher zu übertragen.
-[Prinzip: **Benutzt jemand die Software nur braucht es keine
-API-Dokumentationen; wird die Software aber woanders eingebunden ist dieses
-angeraten.**]{.aside .principle}
-
 ### Versionskontrolle und kontinuierliche Dokumentationspflege
 
-[Prinzip 4: **Die beste Dokumentation ist die, die sich selbst
-schreibt.**]{.aside .principle}
+::: {.callout-tip title="Prinzip" .column-margin}
+
+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
@@ -717,10 +781,10 @@ 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_. [Prinzip: **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}
+Codeversion immer eine aktuelle Doku hat_.
+
+Schlussendlich muss aber das Level an Automation für jedes Projekt individuell
+abgewogen werden.
 
 ## Best Practices, Vorlagen und Checklisten
 
@@ -749,8 +813,8 @@ Dokumentation zu überprüfen:
    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
+   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,
@@ -779,11 +843,7 @@ Diese Checkliste kann vor einem “Release” der Software durchgegangen werden,
 die viele dieser Punkte abdecken). Sie hilft zu entscheiden, was noch
 dokumentiert werden muss und was eventuell weggelassen werden kann. **Alles, was
 für die obigen Punkte nicht relevant ist, kann man tendenziell aus der
-Hauptdokumentation herauslassen.** Beispielsweise interne
-Code-Refaktorierungsdetails oder historische Anekdoten zur Entwicklung gehören
-eher ins interne Changelog oder in Blog-Posts, nicht in die Nutzerdokumentation.
-
-### Zusammenfassung Best Practices
+Hauptdokumentation herauslassen.**
 
 ## Fazit
 
@@ -791,32 +851,22 @@ Die hier präsentierten Anforderungen und Empfehlungen bieten einen **Leitfaden
 für die Dokumentation von Forschungssoftware** in den Digital Humanities. Sie
 sind darauf ausgerichtet, mit überschaubarem Aufwand maximale
 **Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit** zu erreichen.
+
 Indem zentrale Inhalte (Ziele, Inputs/Outputs, Hintergrund, etc.) klar
 dokumentiert, ein nutzerfreundliches Format (README im Repo) gewählt, der Umfang
 fokussiert gehalten und hilfreiche Tools eingesetzt werden, kann die
 Dokumentation zur Stärke eines Projekts werden statt einem lästigen Anhängsel.
 
-Eine gute Dokumentation _erzählt eine klare Geschichte_ über die Software,
-anstatt den Leser mit irrelevanten Details zu verlieren. Mit den richtigen
-Werkzeugen und Prinzipien an der Hand kann selbst unter Zeitdruck eine
-qualitativ hochwertige Dokumentation entstehen – zur Freude aller, die mit der
-Forschungssoftware arbeiten möchten.
-
-Wissenschaftlich fundierte Best Practices – von _Ten Simple Rules for
-Documenting Scientific Software_[@PrlicProcter2012TenSimpleRules] bis zu den
-_ENDINGS-Principles_[@EndingsPrinciples221] – 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**.
+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}
 
@@ -879,14 +929,32 @@ Community (kostenfrei; limitierte features) oder Enterprise-Linzenz"
   (z.b. fehlende Dokumentation) hin.
 - [rst][]: Alternative zu Markdown.
 
-[argparse]: ...
-[Sphinx]: ...
-[MkDocs]: ...
-[Doxygen]: ...
-[Roxygen]: ...
-[Javadoc]: ...
-[pdoc]: ...
-[Docstring]: ...
+[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/

background/extra-styles.css

@@ -0,0 +1,3 @@
+.bad-practice {
+  color: #888888;
+}