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
+berücksichtigen Best Practices des Research Software Engineering (RSE) und damit
-insbesondere die Prinzipien des _Endings-Projekts_ für digitale Langlebigkeit
+einhergehender Prinzipien wie die des _Endings-Projekts_ für digitale
-[@EndingsPrinciples221]. Ziel ist es, ein praxistaugliches Gerüst
+Langlebigkeit [@EndingsPrinciples221] und _FAIR-Prinzipien_ für
-bereitzustellen, das – trotz Zeitknappheit – die wesentlichen
+Software[@BarkerEtAl2022IntroducingFAIR].
-Dokumentationsaspekte abdeckt, um sowohl die **Nachvollziehbarkeit** der
+
-Ergebnisse als auch eine **Weiterverwendung** der Software zu ermöglichen. Im
+Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz
-Folgenden werden die Anforderungen an Inhalt, Format und Umfang der
+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
+und die korrespondierende Ausgabe.
-Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies
+
-umfasst die **Datenmodelle** (etwa wichtige Felder, deren Bedeutung und
+Falls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie
-kontrollierte Vokabulare) und Annahmen über die Daten. Gemäß den
+diese Daten und ihre Struktur. Dies umfasst die **Datenmodelle** (etwa wichtige
-ENDINGS-Prinzipien sollte die Datenstruktur in einem _statischen Dokument_
+Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die
-festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie
+Daten.
-die Software die Daten interpretiert [@EndingsPrinciples221]. Eine Tabelle oder
+
-Auflistung der Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht
+Gemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem _statischen
-die Klarheit. [Beispiel: _“Eingabedatei: CSV mit Spalten `Autor`, `Empfänger`,
+Dokument_ festgehalten und der Software beigelegt sein – so bleibt
-...; Ausgabe: JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”_]{.aside}
+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,
+Kontext_ ^[Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation
-Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in
+von rein kommerzieller Dokumentation: Es geht nicht nur um _wie_ man das Tool
-Überblicksform. Verweisen Sie auf _relevante Publikationen_ oder Theorien, damit
+benutzt, sondern auch _warum_ es so funktioniert (Stichwort
-andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise:
+Nachvollziehbarkeit).] offenlegen. Das heißt, erklären Sie die grundlegenden
-_“Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur
+Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind,
-Netzwerkanalyse historischer Korrespondenz.”_ Halten Sie diesen Abschnitt aber
+zumindest in Überblicksform. Verweisen Sie auf _relevante Publikationen_ oder
-prägnant – Details gehören in die Forschungsarbeit selbst. Wichtig ist, dass die
+Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können.
-Dokumentation den **Brückenschlag zwischen Code und Forschung** herstellt. Da
+Beispielsweise: _“Die Implementierung folgt dem Algorithmus von Müller et al.
-viele Wissenschaftler\*innen zentrale Aspekte lieber in ihren Artikeln
+(2019) zur Netzwerkanalyse historischer Korrespondenz.”_ Halten Sie diesen
-dokumentieren, sollte in der Software-Dokumentation zumindest eine
+Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.
-Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer\*innen, unter welchen
+Wichtig ist, dass die Dokumentation den **Brückenschlag zwischen Code und
-Annahmen oder Theorien das Tool funktioniert. [Dieser Hintergrundteil
+Forschung** herstellt. Da viele Wissenschaftler\*innen zentrale Aspekte lieber
-unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller
+in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest
-Dokumentation: Es geht nicht nur um _wie_ man das Tool benutzt, sondern auch
+eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer\*innen, unter
-_warum_ es so funktioniert (Stichwort Nachvollziehbarkeit).]{.aside}
+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
+Geben Sie ehrlich Auskunft über die _Grenzen der Software_:
-**nicht** abgedeckt? Welche Annahmen über die Daten oder Anwendungsszenarien
+
-werden getroffen? Dokumentieren Sie bekannte Probleme oder Einschränkungen
+- Welche Fälle werden **nicht** abgedeckt?
-(z. B. _“funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1
+- Welche **Annahmen** über die Daten oder Anwendungsszenarien werden getroffen?
-Mio. Datensätze, da Speicherbegrenzung”_). Solche Hinweise verhindern
+
-Fehlanwendungen und sparen Nutzern Zeit. Falls es bekannte **Bugs oder
+Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. _“funktioniert
-Workarounds** gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem
+nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da
-Abschnitt "Bekannte Probleme") erwähnt werden. Eine transparente Auflistung von
+Speicherbegrenzung”_). Solche Hinweise verhindern Fehlanwendungen und sparen
-Limitationen erhöht die Vertrauenswürdigkeit und hilft anderen, die Ergebnisse
+Nutzern Zeit.
-richtig einzuordnen. Auch **aussagekräftige Fehlermeldungen** im Programm selbst
+
-sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen,
+Falls es bekannte **Bugs oder Workarounds** gibt, sollten diese ebenfalls (etwa
-sondern dem/der Anwender\*in idealerweise mitteilen, was schiefging und wie es
+in einer FAQ oder einem Abschnitt "Bekannte Probleme") erwähnt werden.
-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
+Auch **aussagekräftige Fehlermeldungen** im Programm selbst sind eine Form von
-schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.
+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
+_“Fehler bitte über GitHub-Issues melden”_) oder auf die Kontaktmöglichkeit
-Autor (E-Mail) gehört dazu. Ebenso können **Community Guidelines** skizziert
+zum\*zur Autor\*in (E-Mail) gehört dazu.
-werden: etwa Codierstandards oder ein Verhaltenskodex, falls Beiträge erwartet
+
-werden. Für kleinere Projekte reicht oft ein Satz wie _“Beiträge durch Pull
+Ebenso können **Community Guidelines** skizziert werden: etwa Codierstandards
-Requests sind willkommen; bei Fragen wenden Sie sich an…”_. [Dieser Aspekt muss
+oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte
-nicht umfangreich sein, zeigt aber Offenheit und sorgt dafür, dass im Falle von
+reicht oft ein Satz wie _“Beiträge durch Pull Requests sind willkommen; bei
-Rückfragen die Hürde für Kontaktaufnahme niedrig ist.]{.aside}
+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
+Nachnutzung nicht zu behindern.
-**zitiert** werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt
+
-_“Zitation”_ oder eine CITATION-Datei beschreibt, welche Publikation oder
+Zudem sollte angegeben werden, wie die Software **zitiert** werden kann (z. B.
-welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben
+DOI, Paper-Referenz). Ein eigener Abschnitt _“Zitation”_ oder eine
-ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass
+**CITATION-Datei** beschreibt, welche Publikation oder welcher DOI bei
-Autor\*innen Credits für ihre Software bekommen
+Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies
-[@SmithEtAl2016Softwarecitation]. Schließlich ist es sinnvoll, eine
+erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor\*innen Credits
-**Versionsnummer** der Software zu nennen (idealerweise in README und im Tool
+für ihre Software bekommen [@NoyEtAl2019IndustryscaleKnowledge].
-selbst), damit Nutzer wissen, auf welche Ausgabe sich die Dokumentation bezieht
+
-– insbesondere, wenn es im Laufe der Zeit Aktualisierungen gibt. Diese Praxis
+Schließlich ist es sinnvoll, eine **Versionsnummer** der Software zu nennen
-entspricht auch den ENDINGS-Prinzipien, die verlangen, dass jede veröffentlichte
+(idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche
-Version eindeutig erkennbar ist und zitiert werden kann.
+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_
+Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten:
-tut die Software, _warum_ wurde sie geschrieben (wissenschaftlicher Zweck),
+
-_wer_ soll sie nutzen, _wie_ wird sie benutzt (Inputs, Outputs, Abläufe),
+- _Was_ tut die Software,
-_womit_ läuft sie (Umgebung/Abhängigkeiten), _unter welchen Bedingungen_
+- _warum_ wurde sie geschrieben (wissenschaftlicher Zweck),
-(Annahmen/Limitationen) und _wohin_ können sich Nutzer wenden
+- _wer_ soll sie nutzen,
-(Support/Zitation). All diese Punkte sorgen für **Nachvollziehbarkeit** (im
+- _wie_ wird sie benutzt (Inputs, Outputs, Abläufe),
-Sinne von Reproduzierbarkeit der Ergebnisse) und **Weiterverwendbarkeit** (im
+- _womit_ läuft sie (Umgebung/Abhängigkeiten),
-Sinne von Adaptierbarkeit der Software für neue Kontexte).
+- _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
+leicht pflegbar und ohne Spezialsoftware** erstellbar sein.
-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
+Punkte:
-Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie [GitHub][], [GitLab][]
+
-etc. wird die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die
+- Zweck der Software,
-Vorteile von **[Markdown][]** sind die einfache Lesbarkeit in Rohform, die
+- Kurzbeschreibung,
-breite Unterstützung (auch in Renderern wie GitHub-Webansicht) und die Eignung
+- Installation,
-für Versionierung (Textdatei im [git][]). So bleibt die Dokumentation eng mit
+- kurzer Nutzungsbeispiel,
-dem Code verzahnt und unter Versionskontrolle – ein Prinzip, das auch von
+- Kontakt/Lizenz.
-ENDINGS[@EndingsPrinciples221] propagiert wird (Dokumentation soll statisch und
+
-zusammen mit den Daten/Code abgelegt werden).
+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
+Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie
-auffindbar sind. Sie kommen ohne spezielle Tools aus – ein einfacher Texteditor
+leicht auffindbar sind.
-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.**
 
 ### Ü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
+manchen Plattformen.
-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
+Achten Sie darauf, pro Abschnitt nur zusammenhängende Informationen zu behandeln
-Dokumentation.
+(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,
+etc.).
-Diagramme wenn möglich als SVG für Langlebigkeit). Falls Diagramme der
+
-Architektur oder Workflow-Abbildungen hilfreich sind, können diese mit simplen
+Achten Sie dabei auf Dateigrößen und Formate (Bilder als PNG/JPG, Diagramme wenn
-Mitteln erstellt werden (zur Not handgezeichnet und abfotografiert, besser
+möglich als SVG für Langlebigkeit). Falls Diagramme der Architektur oder
-jedoch mit Tools wie [mermaid.js][] Diagrammen in [Markdown][] oder
+Workflow-Abbildungen hilfreich sind, können diese mit simplen Mitteln erstellt
-[graphviz][]). Diese Visualisierungen sind jedoch nur dann einzusetzen, wenn sie
+werden^[zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie
-echten Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden
+[mermaid.js][] Diagrammen in [Markdown][] oder [graphviz][]].
-können. Im Zweifel hat textuelle Beschreibung Vorrang, um nicht vom **Prinzip
+
-“keep it simple”** abzuweichen.
+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
+lange, die nichts aussagt.
-Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel
-ausführen?**]{.aside .principle}
 
 ### 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
+  sich an Entwickler\*innen, während die Nutzendendokumentation sich auf Nutzung
-  Kontext beschränkt
+  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,
+Entwickler\*innendokumentation (z. B. detaillierte API-Dokumente,
-technische Architektur) kann separat gehalten werden, sofern nötig, um den
+Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern
-Hauptnutzerfluss nicht zu überfrachten.
+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
+**“Zukünftiges Ich”**, **Kolleg\*innen**, **Fachforscher\*innen anderer
-ggf. **Software-Entwickler, die den Code erweitern**. Jede dieser Gruppen möchte
+Disziplin** und ggf. **Software-Entwickler\*innen, die den Code erweitern**.
-bestimmte Dinge wissen.
+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
+Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für
-(z. B. Code-Struktur, To-do-Liste) können separat oder später ergänzt werden.
+Entwickler\*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später
-Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwicklerdokus
+ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche
-ohnehin nicht nötig – hier reicht es, den Code gut zu kommentieren und eventuell
+Entwickler\*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code
-eine grobe Architekturübersicht bereitzustellen. Konzentrieren Sie die
+gut zu kommentieren und eventuell eine grobe Architekturübersicht
-Hauptdokumentation darauf, **das Nutzen und Verstehen der Software von außen**
+bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, **das Nutzen
-zu ermöglichen.
+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
+**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
-**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht[Die ENDINGS-Prinzipien für
+**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.
-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}.
 
-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
+Notebooks erfordern eine lauffähige Umgebung – das heißt, Sie müssen darauf
-darauf achten, dass alle Abhängigkeiten im Notebook deklariert sind und die
+achten, dass alle Abhängigkeiten im Notebook deklariert sind oder ggf.
-Daten zugänglich sind. Es hat sich gezeigt, dass Notebooks aus Publikationen oft
+nachinstalliert werden und die Daten zugänglich sind.
-nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen
+
-fehlen. Deshalb: Wenn Sie Notebooks als Doku nutzen, stellen Sie sicher, dass
+Es hat sich gezeigt, dass Notebooks aus Publikationen oft nicht ohne Weiteres
-sie _leicht ausführbar_ sind (z. B. durch Bereitstellen von Umgebungsdateien wie
+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
+Anweisungen im Notebook). Ggf. kann man zusätzlich auch reine
-exportieren und dem Repo beilegen, damit zumindest statisch die Inhalte
+Markdown/HTML-Exporte von evaluierten Notebooks exportieren und dem Repo
-einsehbar sind.
+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
+aktualisieren.
-`>5 Module` lohnt es sich, eine generierte Dokumentation bereitzustellen, um
-(auch selbst) den Überblick zu behalten.**]{.aside .principle}
 
 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
+z. B. in Form von **Docstrings^[kurz für: "Documentation String"]** (mehrzeilige
-Funktionen/Klassen bei Python, [Roxygen][]-Kommentare in R,
+Strings in Funktionen/Klassen bei Python, [Roxygen][]-Kommentare in R,
-[Javadoc][]-Kommentare in Java, etc.). Diese dienen doppelt: Zum einen
+[Javadoc][]-Kommentare in Java, etc.).
-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
+Diese dienen doppelt: Zum einen erleichtern sie es Ihnen und Kollegen, den Code
-verarbeitet werden. Idealerweise dokumentieren Sie _jede wichtige **oder** von
+beim Lesen zu verstehen, zum anderen können sie von Tools ausgelesen und zu
-außen sichtbare Funktion, Klasse oder Modul_ mit einem kurzen Docstring, der
+hübschen API-Dokumentationen verarbeitet werden. Idealerweise dokumentieren Sie
-Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte
+_jede wichtige **oder** von außen sichtbare Funktion, Klasse oder Modul_ mit
-genügen ggf. Modul- oder Abschnittskommentare.[Prinzip 3: **Benutzt jemand die
+einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele
-Software nur braucht es keine API-Dokumentationen; wird die Software aber
+enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.
-woanders eingebunden ist dieses angeraten.**]{.aside .principle}
 
 Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres
-Ökosystems (z. B. **[Google Style Guide](https://google.github.io/styleguide/)**
+Ökosystems (z. B. [Google Style Guide](https://google.github.io/styleguide/) für
-für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen).
+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
+::: {.callout-tip title="Prinzip" .column-margin}
-schreibt.**]{.aside .principle}
+
+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
+Codeversion immer eine aktuelle Doku hat_.
-Automation ist für kleine Projekte evtl. zu viel, aber das Prinzip
+
-“Dokumentation versionieren” ist allgemeingültig, um die Entwicklungshistorie
+Schlussendlich muss aber das Level an Automation für jedes Projekt individuell
-konsistent zu halten.**]{.aside}
+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
+   genannt? Weiß ein\*e Nutzer\*in, welche Fälle nicht abgedeckt sind oder
-   zu achten ist (z. B. Datenqualität, maximale Größen)? Transparenz hier
+   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
+Hauptdokumentation herauslassen.**
-Code-Refaktorierungsdetails oder historische Anekdoten zur Entwicklung gehören
-eher ins interne Changelog oder in Blog-Posts, nicht in die Nutzerdokumentation.
-
-### Zusammenfassung Best Practices
 
 ## 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,
+So schließt sich der Kreis zwischen guter **Softwareentwicklung** und guter
-anstatt den Leser mit irrelevanten Details zu verlieren. Mit den richtigen
+**Wissenschaft**[@Forschungsgemeinschaft2025LeitlinienzurSicherung, Leitlinie
-Werkzeugen und Prinzipien an der Hand kann selbst unter Zeitdruck eine
+12]: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent
-qualitativ hochwertige Dokumentation entstehen – zur Freude aller, die mit der
+verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch
-Forschungssoftware arbeiten möchten.
+wie die Erfahrung zeigt, zahlen sich diese in Form von _Zeiteinsparung bei
-
+Nutzern, höherer Zitierbarkeit und größerer Wirkung_ der Software aus. Mit
-Wissenschaftlich fundierte Best Practices – von _Ten Simple Rules for
+diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre
-Documenting Scientific Software_[@PrlicProcter2012TenSimpleRules] bis zu den
+Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen –
-_ENDINGS-Principles_[@EndingsPrinciples221] – untermauern diesen Katalog. Die
+trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: **Gut
-Umsetzung dieser Richtlinien wird dazu beitragen, dass Forschungssoftware aus
+dokumentierte Forschungscode ist nachhaltige Forschung**.
-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 {.appendix}
 
@@ -879,14 +929,32 @@ Community (kostenfrei; limitierte features) oder Enterprise-Linzenz"
   (z.b. fehlende Dokumentation) hin.
 - [rst][]: Alternative zu Markdown.
 
-[argparse]: ...
+[argparse]:
-[Sphinx]: ...
+  https://docs.python.org/3/library/argparse.html
-[MkDocs]: ...
+  "Der Argument-Parser der Python-Standardbibliothek"
-[Doxygen]: ...
+[Sphinx]:
-[Roxygen]: ...
+  https://www.sphinx-doc.org
-[Javadoc]: ...
+  "Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter
-[pdoc]: ...
+readthedocs.com steht."
-[Docstring]: ...
+[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;
+}