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