updated documentation.md

Writing/documentation.md

@@ -106,12 +106,12 @@ Beschreiben Sie _was die Software tut_ und _warum sie entwickelt wurde_. Nennen
 Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung,
 die mit der Software adressiert wird, sowie die _Zielgruppe_ (wer soll sie
 nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.
-Beispiel: _“Dieses Tool extrahiert Personen-Netzwerke aus historischen
-Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”_ Eine klare
-Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher
-Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die
-eigene Herangehensweise einordnen (z. B. was die Software anders oder besser
-macht).
+[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
 
@@ -164,10 +164,10 @@ 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
+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.
+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
@@ -182,10 +182,9 @@ 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.
+[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.
@@ -193,8 +192,8 @@ 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
+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
@@ -236,15 +235,18 @@ Aktualisierungen gibt[@EndingsPrinciples221].
 
 ### Zusammenfassung der inhaltlichen Anforderungen
 
-Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten:
+::: {.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).
+- [ ] _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

dist/Writing/documentation.html

@@ -752,9 +752,9 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
 <section id="inhaltliche-anforderungen-an-die-dokumentation" class="level2 page-columns page-full">
 <h2 class="anchored" data-anchor-id="inhaltliche-anforderungen-an-die-dokumentation">Inhaltliche Anforderungen an die Dokumentation</h2>
 <p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="EndingsPrinciples221 Lamprecht2020TowardsFAIRPrinciples">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>, <a href="#ref-Lamprecht2020TowardsFAIRPrinciples" role="doc-biblioref">4</a>]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
-<section id="ziel-und-zweck-der-software-statement-of-need" class="level3">
+<section id="ziel-und-zweck-der-software-statement-of-need" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="ziel-und-zweck-der-software-statement-of-need">Ziel und Zweck der Software (Statement of Need)</h3>
-<p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em> 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).</p>
+<div class="page-columns page-full"><p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.  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).</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em></span></div></div>
 </section>
 <section id="input-output-spezifikation-und-datenbeschreibung" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="input-output-spezifikation-und-datenbeschreibung">Input-/Output-Spezifikation und Datenbeschreibung</h3>
@@ -770,19 +770,19 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
 <section id="wissenschaftlicher-hintergrund-und-theoretischer-kontext" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="wissenschaftlicher-hintergrund-und-theoretischer-kontext">Wissenschaftlicher Hintergrund und theoretischer Kontext</h3>
 <p>Da es sich um Forschungssoftware handelt, sollten Sie den <em>wissenschaftlichen Kontext</em> <a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.</p>
-<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup>&nbsp;Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al.&nbsp;(2019) zur Netzwerkanalyse historischer Korrespondenz.”</em> Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p>
+<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup>&nbsp;Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><div class="page-columns page-full"><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können.  Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al.&nbsp;(2019) zur Netzwerkanalyse historischer Korrespondenz.”</em></span></div></div>
 <p>Wichtig ist, dass die Dokumentation den <strong>Brückenschlag zwischen Code und Forschung</strong> 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.</p>
 </section>
-<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3">
+<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="bekannte-limitationen-annahmen-und-fehlermeldungen">Bekannte Limitationen, Annahmen und Fehlermeldungen</h3>
 <p>Geben Sie ehrlich Auskunft über die <em>Grenzen der Software</em>:</p>
 <ul>
 <li>Welche Fälle werden <strong>nicht</strong> abgedeckt?</li>
 <li>Welche <strong>Annahmen</strong> über die Daten oder Anwendungsszenarien werden getroffen?</li>
 </ul>
-<p>Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. <em>“funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”</em>). Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.</p>
+<div class="page-columns page-full"><p> Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispielsweise: <em>“funktioniert nur für Deutschsprachige Texte”</em> oder <em>“maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”</em></span></div></div>
 <p>Falls es bekannte <strong>Bugs oder Workarounds</strong> gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.</p>
-<p>Auch <strong>aussagekräftige Fehlermeldungen</strong> 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. <em>“Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”</em>). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.</p>
+<div class="page-columns page-full"><p>Auch <strong>aussagekräftige Fehlermeldungen</strong> 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.  Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”</em></span></div></div>
 </section>
 <section id="weiterentwicklung-und-beitragsmöglichkeiten" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="weiterentwicklung-und-beitragsmöglichkeiten">Weiterentwicklung und Beitragsmöglichkeiten</h3>
@@ -797,16 +797,27 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
 </section>
 <section id="zusammenfassung-der-inhaltlichen-anforderungen" class="level3">
 <h3 class="anchored" data-anchor-id="zusammenfassung-der-inhaltlichen-anforderungen">Zusammenfassung der inhaltlichen Anforderungen</h3>
-<p>Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantworten:</p>
-<ul>
-<li><em>Was</em> tut die Software,</li>
-<li><em>warum</em> wurde sie geschrieben (wissenschaftlicher Zweck),</li>
-<li><em>wer</em> soll sie nutzen,</li>
-<li><em>wie</em> wird sie benutzt (Inputs, Outputs, Abläufe),</li>
-<li><em>womit</em> läuft sie (Umgebung/Abhängigkeiten),</li>
-<li><em>unter welchen Bedingungen</em> (Annahmen/Limitationen) und</li>
-<li><em>wohin</em> können sich Nutzer wenden (Support/Zitation).</li>
+<div class="callout callout-style-default callout-important callout-titled" title="Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten">
+<div class="callout-header d-flex align-content-center">
+<div class="callout-icon-container">
+<i class="callout-icon"></i>
+</div>
+<div class="callout-title-container flex-fill">
+Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantworten
+</div>
+</div>
+<div class="callout-body-container callout-body">
+<ul class="task-list">
+<li><label><input type="checkbox"><em>Was</em> tut die Software,</label></li>
+<li><label><input type="checkbox"><em>warum</em> wurde sie geschrieben (wissenschaftlicher Zweck),</label></li>
+<li><label><input type="checkbox"><em>wer</em> soll sie nutzen,</label></li>
+<li><label><input type="checkbox"><em>wie</em> wird sie benutzt (Inputs, Outputs, Abläufe),</label></li>
+<li><label><input type="checkbox"><em>womit</em> läuft sie (Umgebung/Abhängigkeiten),</label></li>
+<li><label><input type="checkbox"><em>unter welchen Bedingungen</em> (Annahmen/Limitationen) und</label></li>
+<li><label><input type="checkbox"><em>wohin</em> können sich Nutzer wenden (Support/Zitation).</label></li>
 </ul>
+</div>
+</div>
 <p>All diese Punkte sorgen für <strong>Nachvollziehbarkeit</strong> (im Sinne von Reproduzierbarkeit der Ergebnisse) und <strong>Weiterverwendbarkeit</strong> (im Sinne von Adaptierbarkeit der Software für neue Kontexte).</p>
 </section>
 </section>
@@ -913,7 +924,7 @@ Prinzip
 <p>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<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>.</p>
 <div class="no-row-height column-margin column-container"><div id="fn3"><p><sup>3</sup>&nbsp;zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie <a href="https://mermaid.js.org/" title="Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden">mermaid.js</a> Diagrammen in <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> oder <a href="https://graphviz.org/" title="Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg">graphviz</a></p></div></div><p>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 <strong>Prinzip “keep it simple”</strong> abzuweichen.</p>
 <div class="callout callout-style-default callout-note callout-titled" title="Typische Nutzungsszenarien und Workflows">
-<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-4-contents" aria-controls="callout-4" aria-expanded="false" aria-label="Toggle callout">
+<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="false" aria-label="Toggle callout">
 <div class="callout-icon-container">
 <i class="callout-icon"></i>
 </div>
@@ -922,7 +933,7 @@ Typische Nutzungsszenarien und Workflows
 </div>
 <div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
 </div>
-<div id="callout-4" class="callout-4-contents callout-collapse collapse">
+<div id="callout-5" class="callout-5-contents callout-collapse collapse">
 <div class="callout-body-container callout-body">
 <p>Zeigen Sie anhand von <em>konkreten Beispielen</em>, wie die Software benutzt wird. Ein <strong>Quickstart-Beispiel</strong> 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.</p>
 <p>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. <em>“Analyse eines einzelnen Briefes”</em> vs.&nbsp;<em>“Batch-Verarbeitung eines gesamten Korpus”</em>).</p>

dist/index.html

@@ -672,7 +672,7 @@ window.Quarto = {
 
 <div class="quarto-listing quarto-listing-container-grid" id="listing-listing">
 <div class="list grid quarto-listing-cols-3">
-<div class="g-col-1" data-index="0" data-categories="QXJ0aWNsZSUyQ0Jlc3QlMjBQcmFjdGljZXM=" data-listing-date-sort="1749074400000" data-listing-file-modified-sort="1749133066886" data-listing-date-modified-sort="NaN" data-listing-reading-time-sort="30" data-listing-word-count-sort="5892">
+<div class="g-col-1" data-index="0" data-categories="QXJ0aWNsZSUyQ0Jlc3QlMjBQcmFjdGljZXM=" data-listing-date-sort="1749074400000" data-listing-file-modified-sort="1749137785078" data-listing-date-modified-sort="NaN" data-listing-reading-time-sort="30" data-listing-word-count-sort="5903">
 <a href="./Writing/documentation.html" class="quarto-grid-link">
 <div class="quarto-grid-item card h-100 card-left">
 <p class="card-img-top">

dist/index.xml

@@ -30,9 +30,9 @@
 <section id="inhaltliche-anforderungen-an-die-dokumentation" class="level2 page-columns page-full">
 <h2 class="anchored" data-anchor-id="inhaltliche-anforderungen-an-die-dokumentation">Inhaltliche Anforderungen an die Dokumentation</h2>
 <p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="EndingsPrinciples221 Lamprecht2020TowardsFAIRPrinciples">[1, 4]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
-<section id="ziel-und-zweck-der-software-statement-of-need" class="level3">
+<section id="ziel-und-zweck-der-software-statement-of-need" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="ziel-und-zweck-der-software-statement-of-need">Ziel und Zweck der Software (Statement of Need)</h3>
-<p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em> 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).</p>
+<div class="page-columns page-full"><p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.  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).</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em></span></div></div>
 </section>
 <section id="input-output-spezifikation-und-datenbeschreibung" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="input-output-spezifikation-und-datenbeschreibung">Input-/Output-Spezifikation und Datenbeschreibung</h3>
@@ -48,19 +48,19 @@
 <section id="wissenschaftlicher-hintergrund-und-theoretischer-kontext" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="wissenschaftlicher-hintergrund-und-theoretischer-kontext">Wissenschaftlicher Hintergrund und theoretischer Kontext</h3>
 <p>Da es sich um Forschungssoftware handelt, sollten Sie den <em>wissenschaftlichen Kontext</em> <sup>1</sup> offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.</p>
-<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup>&nbsp;Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al.&nbsp;(2019) zur Netzwerkanalyse historischer Korrespondenz.”</em> Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p>
+<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup>&nbsp;Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><div class="page-columns page-full"><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können.  Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al.&nbsp;(2019) zur Netzwerkanalyse historischer Korrespondenz.”</em></span></div></div>
 <p>Wichtig ist, dass die Dokumentation den <strong>Brückenschlag zwischen Code und Forschung</strong> 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.</p>
 </section>
-<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3">
+<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="bekannte-limitationen-annahmen-und-fehlermeldungen">Bekannte Limitationen, Annahmen und Fehlermeldungen</h3>
 <p>Geben Sie ehrlich Auskunft über die <em>Grenzen der Software</em>:</p>
 <ul>
 <li>Welche Fälle werden <strong>nicht</strong> abgedeckt?</li>
 <li>Welche <strong>Annahmen</strong> über die Daten oder Anwendungsszenarien werden getroffen?</li>
 </ul>
-<p>Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. <em>“funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”</em>). Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.</p>
+<div class="page-columns page-full"><p> Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispielsweise: <em>“funktioniert nur für Deutschsprachige Texte”</em> oder <em>“maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”</em></span></div></div>
 <p>Falls es bekannte <strong>Bugs oder Workarounds</strong> gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.</p>
-<p>Auch <strong>aussagekräftige Fehlermeldungen</strong> 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. <em>“Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”</em>). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.</p>
+<div class="page-columns page-full"><p>Auch <strong>aussagekräftige Fehlermeldungen</strong> 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.  Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.</p><div class="no-row-height column-margin column-container"><span class="margin-aside">Beispiel: <em>“Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”</em></span></div></div>
 </section>
 <section id="weiterentwicklung-und-beitragsmöglichkeiten" class="level3 page-columns page-full">
 <h3 class="anchored" data-anchor-id="weiterentwicklung-und-beitragsmöglichkeiten">Weiterentwicklung und Beitragsmöglichkeiten</h3>
@@ -75,16 +75,27 @@
 </section>
 <section id="zusammenfassung-der-inhaltlichen-anforderungen" class="level3">
 <h3 class="anchored" data-anchor-id="zusammenfassung-der-inhaltlichen-anforderungen">Zusammenfassung der inhaltlichen Anforderungen</h3>
-<p>Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantworten:</p>
-<ul>
-<li><em>Was</em> tut die Software,</li>
-<li><em>warum</em> wurde sie geschrieben (wissenschaftlicher Zweck),</li>
-<li><em>wer</em> soll sie nutzen,</li>
-<li><em>wie</em> wird sie benutzt (Inputs, Outputs, Abläufe),</li>
-<li><em>womit</em> läuft sie (Umgebung/Abhängigkeiten),</li>
-<li><em>unter welchen Bedingungen</em> (Annahmen/Limitationen) und</li>
-<li><em>wohin</em> können sich Nutzer wenden (Support/Zitation).</li>
+<div class="callout callout-style-default callout-important callout-titled" title="Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten">
+<div class="callout-header d-flex align-content-center">
+<div class="callout-icon-container">
+<i class="callout-icon"></i>
+</div>
+<div class="callout-title-container flex-fill">
+Zusammengefasst sollte die Dokumentation alle <strong>W-Fragen</strong> beantworten
+</div>
+</div>
+<div class="callout-body-container callout-body">
+<ul class="task-list">
+<li><label><input type="checkbox"><em>Was</em> tut die Software,</label></li>
+<li><label><input type="checkbox"><em>warum</em> wurde sie geschrieben (wissenschaftlicher Zweck),</label></li>
+<li><label><input type="checkbox"><em>wer</em> soll sie nutzen,</label></li>
+<li><label><input type="checkbox"><em>wie</em> wird sie benutzt (Inputs, Outputs, Abläufe),</label></li>
+<li><label><input type="checkbox"><em>womit</em> läuft sie (Umgebung/Abhängigkeiten),</label></li>
+<li><label><input type="checkbox"><em>unter welchen Bedingungen</em> (Annahmen/Limitationen) und</label></li>
+<li><label><input type="checkbox"><em>wohin</em> können sich Nutzer wenden (Support/Zitation).</label></li>
 </ul>
+</div>
+</div>
 <p>All diese Punkte sorgen für <strong>Nachvollziehbarkeit</strong> (im Sinne von Reproduzierbarkeit der Ergebnisse) und <strong>Weiterverwendbarkeit</strong> (im Sinne von Adaptierbarkeit der Software für neue Kontexte).</p>
 </section>
 </section>
@@ -191,7 +202,7 @@ Prinzip
 <p>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<sup>3</sup>.</p>
 <div class="no-row-height column-margin column-container"><div id="fn3"><p><sup>3</sup>&nbsp;zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie <a href="https://mermaid.js.org/" title="Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden">mermaid.js</a> Diagrammen in <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> oder <a href="https://graphviz.org/" title="Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg">graphviz</a></p></div></div><p>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 <strong>Prinzip “keep it simple”</strong> abzuweichen.</p>
 <div class="callout callout-style-default callout-note callout-titled" title="Typische Nutzungsszenarien und Workflows">
-<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-4-contents" aria-controls="callout-4" aria-expanded="false" aria-label="Toggle callout">
+<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="false" aria-label="Toggle callout">
 <div class="callout-icon-container">
 <i class="callout-icon"></i>
 </div>
@@ -200,7 +211,7 @@ Typische Nutzungsszenarien und Workflows
 </div>
 <div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
 </div>
-<div id="callout-4" class="callout-4-contents callout-collapse collapse">
+<div id="callout-5" class="callout-5-contents callout-collapse collapse">
 <div class="callout-body-container callout-body">
 <p>Zeigen Sie anhand von <em>konkreten Beispielen</em>, wie die Software benutzt wird. Ein <strong>Quickstart-Beispiel</strong> 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.</p>
 <p>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. <em>“Analyse eines einzelnen Briefes”</em> vs.&nbsp;<em>“Batch-Verarbeitung eines gesamten Korpus”</em>).</p>

dist/sitemap.xml

@@ -82,6 +82,6 @@
   </url>
   <url>
     <loc>https://drezil.de/Writing/documentation.html</loc>
-    <lastmod>2025-06-05T14:17:46.886Z</lastmod>
+    <lastmod>2025-06-05T15:36:25.078Z</lastmod>
   </url>
 </urlset>