updated documentation.md

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>