From c757c20ea5c13ceda70ce2ca2855cb4193b9c491 Mon Sep 17 00:00:00 2001 From: Nicole Dresselhaus Date: Thu, 5 Jun 2025 17:37:01 +0200 Subject: [PATCH] updated documentation.md --- Writing/documentation.md | 48 +++++++++++++++++---------------- dist/Writing/documentation.html | 45 +++++++++++++++++++------------ dist/index.html | 2 +- dist/index.xml | 45 +++++++++++++++++++------------ dist/search.json | 2 +- dist/sitemap.xml | 2 +- 6 files changed, 84 insertions(+), 60 deletions(-) diff --git a/Writing/documentation.md b/Writing/documentation.md index 9e60e14..b6b6f9a 100644 --- a/Writing/documentation.md +++ b/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 diff --git a/dist/Writing/documentation.html b/dist/Writing/documentation.html index 43d248c..d62189c 100644 --- a/dist/Writing/documentation.html +++ b/dist/Writing/documentation.html @@ -752,9 +752,9 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.

Inhaltliche Anforderungen an die Dokumentation

Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:

-
+

Ziel und Zweck der Software (Statement of Need)

-

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).

+

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. 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.”

Input-/Output-Spezifikation und Datenbeschreibung

@@ -770,19 +770,19 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.

Wissenschaftlicher Hintergrund und theoretischer Kontext

Da es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext 1 offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.

-

1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).

Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.” Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.

+

1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).

Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.

Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”

Wichtig ist, dass die Dokumentation den Brückenschlag zwischen Code und Forschung herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.

-
+

Bekannte Limitationen, Annahmen und Fehlermeldungen

Geben Sie ehrlich Auskunft über die Grenzen der Software:

  • Welche Fälle werden nicht abgedeckt?
  • Welche Annahmen über die Daten oder Anwendungsszenarien werden getroffen?
-

Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. “funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”). Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.

+

Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.

Beispielsweise: “funktioniert nur für Deutschsprachige Texte” oder “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”

Falls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.

-

Auch aussagekräftige Fehlermeldungen im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann (z. B. “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.

+

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. Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.

Beispiel: “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”

Weiterentwicklung und Beitragsmöglichkeiten

@@ -797,16 +797,27 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.

Zusammenfassung der inhaltlichen Anforderungen

-

Zusammengefasst sollte die Dokumentation alle W-Fragen beantworten:

-
    -
  • Was tut die Software,
    • -
  • warum wurde sie geschrieben (wissenschaftlicher Zweck),
    • -
  • wer soll sie nutzen,
    • -
  • wie wird sie benutzt (Inputs, Outputs, Abläufe),
    • -
  • womit läuft sie (Umgebung/Abhängigkeiten),
    • -
  • unter welchen Bedingungen (Annahmen/Limitationen) und
    • -
  • wohin können sich Nutzer wenden (Support/Zitation).
    • +
    +
    +
    + +
    +
    +Zusammengefasst sollte die Dokumentation alle W-Fragen beantworten +
    +
    +
    +
      +
      • +
      • +
      • +
      • +
      • +
      • +
    +
    +

    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).

@@ -913,7 +924,7 @@ Prinzip

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 werden3.

3 zur Not handgezeichnet und abfotografiert, besser jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder graphviz

Diese Visualisierungen sind jedoch nur dann einzusetzen, wenn sie echten Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im Zweifel hat textuelle Beschreibung Vorrang, um nicht vom Prinzip “keep it simple” abzuweichen.

- -
+

Zeigen Sie anhand von konkreten Beispielen, wie die Software benutzt wird. Ein Quickstart-Beispiel 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.

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. “Analyse eines einzelnen Briefes” vs. “Batch-Verarbeitung eines gesamten Korpus”).

diff --git a/dist/index.html b/dist/index.html index e044735..9e69e55 100644 --- a/dist/index.html +++ b/dist/index.html @@ -672,7 +672,7 @@ window.Quarto = {
-
+

diff --git a/dist/index.xml b/dist/index.xml index 159628c..da79a8b 100644 --- a/dist/index.xml +++ b/dist/index.xml @@ -30,9 +30,9 @@

Inhaltliche Anforderungen an die Dokumentation

Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:

-
+

Ziel und Zweck der Software (Statement of Need)

-

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).

+

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. 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.”

Input-/Output-Spezifikation und Datenbeschreibung

@@ -48,19 +48,19 @@

Wissenschaftlicher Hintergrund und theoretischer Kontext

Da es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext 1 offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.

-

1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).

Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.” Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.

+

1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).

Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.

Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”

Wichtig ist, dass die Dokumentation den Brückenschlag zwischen Code und Forschung herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.

-
+

Bekannte Limitationen, Annahmen und Fehlermeldungen

Geben Sie ehrlich Auskunft über die Grenzen der Software:

  • Welche Fälle werden nicht abgedeckt?
  • Welche Annahmen über die Daten oder Anwendungsszenarien werden getroffen?
-

Dokumentieren Sie bekannte Probleme oder Einschränkungen (z. B. “funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”). Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.

+

Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.

Beispielsweise: “funktioniert nur für Deutschsprachige Texte” oder “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”

Falls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.

-

Auch aussagekräftige Fehlermeldungen im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann (z. B. “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.

+

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. Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.

Beispiel: “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”

Weiterentwicklung und Beitragsmöglichkeiten

@@ -75,16 +75,27 @@

Zusammenfassung der inhaltlichen Anforderungen

-

Zusammengefasst sollte die Dokumentation alle W-Fragen beantworten:

-
    -
  • Was tut die Software,
    • -
  • warum wurde sie geschrieben (wissenschaftlicher Zweck),
    • -
  • wer soll sie nutzen,
    • -
  • wie wird sie benutzt (Inputs, Outputs, Abläufe),
    • -
  • womit läuft sie (Umgebung/Abhängigkeiten),
    • -
  • unter welchen Bedingungen (Annahmen/Limitationen) und
    • -
  • wohin können sich Nutzer wenden (Support/Zitation).
    • +
    +
    +
    + +
    +
    +Zusammengefasst sollte die Dokumentation alle W-Fragen beantworten +
    +
    +
    +
      +
      • +
      • +
      • +
      • +
      • +
      • +
    +
    +

    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).

@@ -191,7 +202,7 @@ Prinzip

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 werden3.

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.

- -
+

Zeigen Sie anhand von konkreten Beispielen, wie die Software benutzt wird. Ein Quickstart-Beispiel 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.

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. “Analyse eines einzelnen Briefes” vs. “Batch-Verarbeitung eines gesamten Korpus”).

diff --git a/dist/search.json b/dist/search.json index 7fe7a54..ddd6398 100644 --- a/dist/search.json +++ b/dist/search.json @@ -1172,7 +1172,7 @@ "href": "Writing/documentation.html#inhaltliche-anforderungen-an-die-dokumentation", "title": "Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)", "section": "Inhaltliche Anforderungen an die Dokumentation", - "text": "Inhaltliche Anforderungen an die Dokumentation\nEin zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:\n\nZiel und Zweck der Software (Statement of Need)\nBeschreiben 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).\n\n\nInput-/Output-Spezifikation und Datenbeschreibung\nDokumentieren 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.\nFalls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies umfasst die Datenmodelle (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten.\nGemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [1]. 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.”\nGerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via JSON-Schema an.\n\n\nCode-Abhängigkeiten und technische Voraussetzungen\nListen Sie alle Abhängigkeiten (Dependencies) der Software auf. Dazu gehören verwendete Programmiersprachen/Versionen, erforderliche Bibliotheken oder Frameworks, und sonstige Systemvoraussetzungen (z. B. Betriebssystem, Mindesthardware, Datenbank-Versionen). Wichtig ist, wie diese Abhängigkeiten installiert werden können. Optimal ist eine automatisierte Installationsroutine (z. B. ein requirements.txt für Python oder ein Paketmanager-Befehl). In jedem Fall sollte die Dokumentation mindestens Schritt-für-Schritt-Installationsanleitungen enthalten (inklusive evtl. benötigter Vorkenntnisse, z. B. “Python 3 erforderlich”). Beispiel: “Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation: pip install -r requirements.txt.” Falls spezielle technische Voraussetzungen bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder große Speicherkapazitäten – sind diese zu nennen.\n\n\nWissenschaftlicher Hintergrund und theoretischer Kontext\nDa es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext 1 offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.\n1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.” Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.\nWichtig ist, dass die Dokumentation den Brückenschlag zwischen Code und Forschung herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.\n\n\nBekannte Limitationen, Annahmen und Fehlermeldungen\nGeben Sie ehrlich Auskunft über die Grenzen der Software:\n\nWelche Fälle werden nicht abgedeckt?\nWelche Annahmen über die Daten oder Anwendungsszenarien werden getroffen?\n\nDokumentieren 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.\nFalls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.\nAuch aussagekräftige Fehlermeldungen im Programm selbst sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen, sondern dem/der Anwender*in idealerweise mitteilen, was schiefging und bestenfalls direkt wie es behoben werden kann (z. B. “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”). Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.\n\n\nWeiterentwicklung und Beitragsmöglichkeiten\nObwohl 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*zur Autor*in (E-Mail) gehört dazu.\nEbenso können Community Guidelines skizziert werden: etwa Code-Standards oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte reicht oft ein Satz wie “Beiträge durch Pull Requests sind willkommen; bei Fragen wenden Sie sich an…”. 2\n2 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.\n\nProjekt-Metadaten (Lizenz, Zitation, Version)\nTeil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[4]. Lizenzinformationen klären die rechtlichen 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.\nZudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [5].\nSchließlich ist es sinnvoll, eine Versionsnummer der Software zu nennen (idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen gibt[1].\n\n\nZusammenfassung der inhaltlichen Anforderungen\nZusammengefasst sollte die Dokumentation alle W-Fragen beantworten:\n\nWas tut die Software,\nwarum wurde sie geschrieben (wissenschaftlicher Zweck),\nwer soll sie nutzen,\nwie wird sie benutzt (Inputs, Outputs, Abläufe),\nwomit läuft sie (Umgebung/Abhängigkeiten),\nunter welchen Bedingungen (Annahmen/Limitationen) und\nwohin können sich Nutzer wenden (Support/Zitation).\n\nAll diese Punkte sorgen für Nachvollziehbarkeit (im Sinne von Reproduzierbarkeit der Ergebnisse) und Weiterverwendbarkeit (im Sinne von Adaptierbarkeit der Software für neue Kontexte).", + "text": "Inhaltliche Anforderungen an die Dokumentation\nEin zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende Big Picture, also eine klare Darstellung des Was und Warum. Die Dokumentation sollte daher alle Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind[1, 4]. Insbesondere sind folgende Inhalte essenziell:\n\nZiel und Zweck der Software (Statement of Need)\nBeschreiben 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. 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.”\n\n\nInput-/Output-Spezifikation und Datenbeschreibung\nDokumentieren 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.\nFalls die Software mit bestimmten Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies umfasst die Datenmodelle (etwa wichtige Felder, deren Bedeutung und kontrollierte Vokabulare) und Annahmen über die Daten.\nGemäß den ENDINGS-Prinzipien sollte die Datenstruktur auch in einem statischen Dokument festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie die Software die Daten interpretiert [1]. 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.”\nGerade für JSON-Dateien bietet es sich an ggf. auch ein formelle Spezifikation via JSON-Schema an.\n\n\nCode-Abhängigkeiten und technische Voraussetzungen\nListen Sie alle Abhängigkeiten (Dependencies) der Software auf. Dazu gehören verwendete Programmiersprachen/Versionen, erforderliche Bibliotheken oder Frameworks, und sonstige Systemvoraussetzungen (z. B. Betriebssystem, Mindesthardware, Datenbank-Versionen). Wichtig ist, wie diese Abhängigkeiten installiert werden können. Optimal ist eine automatisierte Installationsroutine (z. B. ein requirements.txt für Python oder ein Paketmanager-Befehl). In jedem Fall sollte die Dokumentation mindestens Schritt-für-Schritt-Installationsanleitungen enthalten (inklusive evtl. benötigter Vorkenntnisse, z. B. “Python 3 erforderlich”). Beispiel: “Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation: pip install -r requirements.txt.” Falls spezielle technische Voraussetzungen bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder große Speicherkapazitäten – sind diese zu nennen.\n\n\nWissenschaftlicher Hintergrund und theoretischer Kontext\nDa es sich um Forschungssoftware handelt, sollten Sie den wissenschaftlichen Kontext 1 offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.\n1 Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um wie man das Tool benutzt, sondern auch warum es so funktioniert (Stichwort Nachvollziehbarkeit).Verweisen Sie auf relevante Publikationen oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.Beispielsweise: “Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”\nWichtig ist, dass die Dokumentation den Brückenschlag zwischen Code und Forschung herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.\n\n\nBekannte Limitationen, Annahmen und Fehlermeldungen\nGeben Sie ehrlich Auskunft über die Grenzen der Software:\n\nWelche Fälle werden nicht abgedeckt?\nWelche Annahmen über die Daten oder Anwendungsszenarien werden getroffen?\n\n Solche Hinweise verhindern Fehlanwendungen und sparen Nutzern Zeit.Beispielsweise: “funktioniert nur für Deutschsprachige Texte” oder “maximale Datenmenge 1 Mio. Datensätze, da Speicherbegrenzung”\nFalls es bekannte Bugs oder Workarounds gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem Abschnitt “Bekannte Probleme”) erwähnt werden.\nAuch 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. Solche in den Code integrierten Hinweise ergänzen die schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.Beispiel: “Fehler: Ungültiges Datum im Feld XY – bitte Format TT/MM/JJJJ verwenden.”\n\n\nWeiterentwicklung und Beitragsmöglichkeiten\nObwohl 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*zur Autor*in (E-Mail) gehört dazu.\nEbenso können Community Guidelines skizziert werden: etwa Code-Standards oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte reicht oft ein Satz wie “Beiträge durch Pull Requests sind willkommen; bei Fragen wenden Sie sich an…”. 2\n2 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.\n\nProjekt-Metadaten (Lizenz, Zitation, Version)\nTeil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten[4]. Lizenzinformationen klären die rechtlichen 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.\nZudem sollte angegeben werden, wie die Software zitiert werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt “Zitation” oder eine CITATION-Datei beschreibt, welche Publikation oder welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor*innen Credits für ihre Software bekommen [5].\nSchließlich ist es sinnvoll, eine Versionsnummer der Software zu nennen (idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen gibt[1].\n\n\nZusammenfassung der inhaltlichen Anforderungen\n\n\n\n\n\n\nZusammengefasst sollte die Dokumentation alle W-Fragen beantworten\n\n\n\n\nWas tut die Software,\nwarum wurde sie geschrieben (wissenschaftlicher Zweck),\nwer soll sie nutzen,\nwie wird sie benutzt (Inputs, Outputs, Abläufe),\nwomit läuft sie (Umgebung/Abhängigkeiten),\nunter welchen Bedingungen (Annahmen/Limitationen) und\nwohin können sich Nutzer wenden (Support/Zitation).\n\n\n\nAll diese Punkte sorgen für Nachvollziehbarkeit (im Sinne von Reproduzierbarkeit der Ergebnisse) und Weiterverwendbarkeit (im Sinne von Adaptierbarkeit der Software für neue Kontexte).", "crumbs": [ "Home", "Serious", diff --git a/dist/sitemap.xml b/dist/sitemap.xml index c94b49d..30590d4 100644 --- a/dist/sitemap.xml +++ b/dist/sitemap.xml @@ -82,6 +82,6 @@ https://drezil.de/Writing/documentation.html - 2025-06-05T14:17:46.886Z + 2025-06-05T15:36:25.078Z