Forschungssoftware-Dokumentation: Ein praktischer Leitfaden für Wissenschaftler

Sie haben gerade eine Simulations-Pipeline fertiggestellt. Ihre Ergebnisse sind Veröffentlichungsbereit. Ihr Code funktioniert. Warum müssen Sie es also noch dokumentieren?

Denn ohne Dokumentation ist Ihre Software schwerer zu zitieren, schwerer zu reproduzieren und schwerer zu warten. Mitarbeiter verstehen möglicherweise nicht, wie sie ausgeführt werden sollen. Zukünftige Studenten wissen möglicherweise nicht, welche Konfigurationsdatei wichtig ist. Selbst Sie können wichtige Designentscheidungen nach mehreren Monaten vergessen.

Die Dokumentation ist kein nettes Add-On für Forschungssoftware. Es ist die Brücke zwischen einem Arbeitsgerät und einem reproduzierbaren Forschungsgut. Sie müssen kein technischer Redakteur sein, um es gut zu machen. Sie brauchen eine Struktur.

Schlüssel zum Mitnehmen

• Die Dokumentation ist Teil der reproduzierbaren Forschung. Code ohne Dokumentation wird zu einer Black Box, die nur der ursprüngliche Autor pflegen kann.
• Vier Dokumentationstypen erfüllen vier verschiedene Benutzeranforderungen: Lernprogramme, Anleitungen zum Tun, Referenz zum Beschreiben und Erklärung für das Verständnis.
• Das Diátaxis-Framework ist eine praktische Möglichkeit, Forschungssoftware-Dokumentation zu organisieren.
• Die zehn einfachen Regeln zur Dokumentation wissenschaftlicher Software bieten eine nützliche Checkliste zum Schreiben besserer Dokumentation.
• Schablonen und Werkzeuge existieren bereits. Readme-Strukturen, CITATION.cff-Dateien, Sphinx, Mkdocs und Read the Docs machen den Prozess effizienter.

Warum Dokumentation wichtig ist

Forschungssoftware befindet sich zwischen Wissenschaft und Technik. Im Gegensatz zu herkömmlichen Laborgeräten kann Software von jedem mit der richtigen Umgebung geteilt, geändert, wiederverwendet und zitiert werden. Aber dieses Potenzial bedeutet wenig, wenn niemand versteht, wie die Software funktioniert.

Die Einsätze sind praktisch:

• Reproduzierbarkeit. Ohne Dokumentation können andere Forscher Ihre Arbeit nicht zuverlässig verifizieren oder wiederverwenden.
• Zitat. Software, die keine Anleitung und Gebrauchsanweisungen enthält, wird weniger wahrscheinlich gut belastet.
• Aufrechterhaltung Wenn ein Forscher ein Labor verlässt, wird undokumentierter Code oft zu technischen Schulden für die nächste Person.

Eine gute Dokumentation erleichtert die Verwendung, Erweiterung, Überprüfung und Aufbewahrung von Software. Es reduziert auch die Anzahl der wiederholten Fragen von Mitarbeitern und zukünftigen Benutzern.

Dieser Leitfaden bietet Ihnen einen praktischen Rahmen und Vorlagen für die effektive Dokumentation der Forschungssoftware.

Das Diátaxis-Framework: Vier Arten von Dokumentation

Wenn Ihre Dokumentation derzeit in einer langen Readme-Datei lebt, fühlt sie sich möglicherweise unorganisiert. Tutorials, Installationshinweise, API-Details, Theorie, Beispiele und Fehlerbehebung können leicht zusammengemischt werden.

Das Diátaxis-Framework löst dies, indem die Dokumentation in vier verschiedene Typen unterteilt wird. Jeder Typ dient einem anderen Benutzerbedarf.

1. Tutorials

Ein Tutorial ist lernorientiert. Es führt einen Anfänger durch einen geführten Weg und hilft ihm, ein konkretes Ergebnis zu erzielen.

Beispiel: „FiPy für Ihre erste Phasenfeldsimulation einrichten.“

Ein Tutorial Antworten: Wie lerne ich, diese Software zu verwenden?

2. Anleitungen

Eine Anleitung ist handlungsorientiert. Es hilft jemandem, eine bestimmte Aufgabe zu erledigen, nachdem er die Grundlagen bereits verstanden hat.

Beispiele sind:

• So führen Sie eine Monte-Carlo-Simulation mit Fipy durch.
• So beheben Sie Konvergenzfehler.
• So exportieren Sie Simulationsergebnisse nach CSV.

Eine Anleitung zur Anleitung: Wie erreiche ich eine bestimmte Aufgabe?

3. Referenz

Die Referenzdokumentation ist informationsorientiert. Es ist sachlich, neutral und vollständig. Es beschreibt, was die Software liefert, ohne zu unterrichten oder zu überzeugen.

Beispiele sind:

• API-Dokumentation.
• Funktionssignaturen.
• Parameterspezifikationen.
• Klassendefinitionen.

Referenzdokumentation Antworten: Was macht das?

4. Erklärung

Erklärung ist verständnisorientiert. Es bietet Hintergrund-, Kontext-, Argumentations- und Designgründe.

Beispiele sind:

• Warum der Solver implizite Zeitschritte verwendet.
• Das mathematische Modell hinter der Implementierung.
• Warum eine Mesh-Strategie einer anderen gegenüber gewählt wurde.

Erklärung Antworten: Warum funktioniert das so?

Die zehn einfachen Regeln zur Dokumentation von Forschungssoftware

Die zehn einfachen Regeln zur Dokumentation wissenschaftlicher Software sind eine praktische Checkliste für die Dokumentationsqualität. Sie sind nützlich, weil sie sich auf Gewohnheiten konzentrieren, die Forscher anwenden können, ohne eine vollständige Dokumentationsabteilung aufzubauen.

Regel 1: Schreiben Sie Kommentare, während Sie codieren

Kommentare sollten die Ideen und Gründe für den Algorithmus erklären und nicht nur das wiederholen, was der Code bereits sagt.

# Good: explains why this approach is used
# Use implicit time stepping for stiff reaction terms to avoid
# timestep restrictions that would make the simulation impractical.
solver = ImplicitTimeStepping(reaction_terms)

# Bad: repeats the line without explaining intent
solver = ImplicitTimeStepping(reaction_terms)  # creates solver

Regel 2: Viele Beispiele enthalten

Beispiele zeigen den Benutzern, wie die Software in der Praxis funktioniert. Geben Sie ausführbare Beispiele an, die den Hauptworkflow demonstrieren.

Wenn die Dokumentation mit Beispielen zu voll wird, verschieben Sie sie in ein dediziertes examples/-Verzeichnis und verknüpfen Sie sie aus der Hauptdokumentation.

Regel 3: Fügen Sie eine Kurzanleitung hinzu

In einer Kurzanleitung sollte jemand die Software innerhalb weniger Minuten nach dem Herunterladen verwenden. Es sollte die Installation, ein minimales Beispiel und die erwartete Ausgabe enthalten.

Ohne einen Schnellstart gehen viele Benutzer davon aus, dass die Software zu schwierig zu bedienen ist und vor dem Testen verlassen wird.

Regel 4: Schreiben Sie eine umfassende Readme

Angenommen, die Readme wird die einzige Dokumentation sein, die viele Benutzer lesen. Es sollte das Wesentliche klar abdecken.

Eine starke Readme sollte enthalten:

• Eine kurze Projektbeschreibung.
• Installationsanleitungen und Abhängigkeiten.
• Ein Schnellstart-Beispiel.
• Lizenzinformationen.
• Zitieranweisungen.
• Ein Link zur vollständigen Dokumentation.

Readme-Vorlage:

# Project Name

Short description: one sentence explaining what the software does.

## Installation

1. Clone this repository.
2. Run `pip install -e .` or your preferred install command.
3. Verify the installation:

```python
import mypackage
print(mypackage.__version__)
```

## Quickstart

```python
from mypackage import MySimulator

sim = MySimulator(config="default.yaml")
results = sim.run()
```

## Documentation

Full documentation: [Read the Docs link]

## Citation

Please cite this software using the CITATION.cff file.

## License

MIT License

Regel 5: Fügen Sie einen Hilfebefehl für CLIs ein

Wenn Ihre Software über eine Befehlszeilenschnittstelle verfügt, schließen Sie das Flag --help ein. Es sollte Befehle, erforderliche Argumente, optionale Parameter und Beispiele erläutern.

Python-Tools wie argparse machen dies einfach.

Regel 6: Versionskontrolle Ihre Dokumentation

Bewahren Sie die Dokumentation neben dem Code in der Versionskontrolle auf. Benutzer älterer Softwareversionen benötigen Zugriff auf diese Versionen.

Verwenden Sie nach Möglichkeit versioniertes Dokumentations-Hosting, damit Benutzer zwischen den Versionen wechseln können.

Regel 7: Dokumentieren Sie Ihre API

Dokumentieren Sie öffentliche Funktionen, Klassen, Argumente, Rückgabewerte und Ausnahmen. Verwenden Sie einen konsistenten DocString-Stil, damit automatisierte Tools lesbare API-Dokumentation generieren können.

Beispiel:

def run_simulation(config_path, steps):
    """Run the simulation from a configuration file.

    Args:
        config_path: Path to the YAML configuration file.
        steps: Number of time steps to run.

    Returns:
        Simulation results object with fields, metadata, and diagnostics.

    Raises:
        ValueError: If the configuration file is invalid.
    """
    ...

Regel 8: Verwenden Sie automatisierte Dokumentationstools

Schreiben Sie nicht alles manuell, wenn Tools einen Teil davon generieren können. Automatisierte Dokumentationswerkzeuge reduzieren sich wiederholende Arbeiten und halten die Dokumentation näher am Code.

Nützliche Werkzeuge sind:

• Sphinx für Python-Pakete mit komplexen APIs.
• Mkdocs für einfache markdown-basierte Dokumentationsseiten.
• Lesen Sie die Dokumente für das Hosting und die automatischen Dokumentationserstellungen.

Regel 9: Schreiben Sie umsetzbare Fehlermeldungen

Gute Fehlermeldungen sagen den Benutzern, was schief gelaufen ist, warum es passiert ist und wie man es behebt.

# Bad
raise ValueError("Invalid input")

# Good
raise ValueError(
    f"Input parameter 'temperature' must be between 0 and 3000 K. "
    f"Received {temperature} K. Check your simulation config file."
)

Dies spart Debug-Zeit und reduziert Supportanfragen.

Regel 10: Sagen Sie den Leuten, wie Sie Ihre Software zitieren sollen

Wenn Sie möchten, dass Ihre Forschungssoftware Guthaben erhält, geben Sie Anweisungen zum Zitat. Schließen Sie eine doi-, bibtex- und CITATION.cff-Datei ein.

Wenn die Software keine Zeitschriftenveröffentlichung hat, verwenden Sie zenodo, um ein DOI für Releases zu prägen. Die Einreichung an das Journal of Open Source Software kann auch das Zitieren von Software erleichtern.

Dokumentationsvorlagen, die Sie heute verwenden können

der Dokumentationsentscheidungsbaum

Stellen Sie vor dem Schreiben der Dokumentation drei Fragen:

1. Für wen ist es? Benutzer, Entwickler, Betreuer, Rezensenten oder Mitarbeiter?
2. Was wollen sie? Führen Sie die Software aus, ändern Sie sie, verstehen Sie das Modell oder zitieren Sie es?
3. Welches Format entspricht dem Bedarf? Tutorial, Anleitung, Referenz, Erklärung, Inline-Kommentar oder API-Seite?

Diese Fragen verhindern einen häufigen Fehler: Schreiben eines überladenen Dokuments für jedes Publikum.

das Zitierdateiformat

Die CITATION.cff-Datei ist eine maschinenlesbare und menschenlesbare Datei für das Software-Zitat. Es kann enthalten:

• Softwarename und Version.
• Autoren und Zugehörigkeiten.
• DOI für die Software.
• BibTeX-Informationen.
• Repository-URL.

In Verbindung mit einem zenodo doi wird CITATION.cff zu einem stabilen Zitationsdatensatz für Ihre Software.

Beispiel citation.cff Vorlage

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "Project Name"
version: "1.0.0"
doi: "10.5281/zenodo.xxxxxxx"
authors:
  - family-names: "Surname"
    given-names: "First Name"
    affiliation: "Research Institution"
repository-code: "https://github.com/username/project-name"
license: "MIT"

Handwerkszeug

häufige Fehler und wie man sie vermeidet

Fehler 1: Alles als Readme behandeln

Eine Readme kann nicht jeden Job gut machen. Wenn Sie Tutorials, Referenzen, Erklärungen, API-Details und Fehlerbehebung in einer Datei kombinieren, haben Benutzer Schwierigkeiten, das zu finden, was sie benötigen.

Trennen Sie die Dokumentation nach Verwendungszweck der Diátaxis-Quadranten.

Fehler 2: Erklärung in Tutorials schreiben

Tutorials sollten kurz, praktisch und linear sein. Wenn ein Anfänger das mathematische Modell vor der Verwendung der Software verstehen muss, legen Sie diese Erklärung auf eine separate Seite und verlinken Sie darauf.

Fehler 3: Nicht versionskontrollierende Dokumentation

Wenn Sie in Version 2.0 einen Standardparameter ändern, benötigen Benutzer der Version 1.5 die alte Dokumentation. Versionierte Dokumente verhindern Verwirrung und machen ältere Releases nutzbarer.

Fehler 4: Angenommen, Sie werden sich an alles erinnern

Sie können sich sechs Monate später nicht an Ihre Designentscheidungen erinnern. Kommentare und Erklärungsseiten dienen als Labornotiz für Ihre Implementierungsentscheidungen.

Fehler 5: Zitatanweisungen vergessen

Software ohne Zitationsberatung erhält oft weniger Guthaben. Fügen Sie eine doi-, bibtex- und CITATION.cff-Datei ein, damit die Benutzer genau wissen, wie Sie Ihre Arbeit zitieren können.

Ein praktischer Dokumentationsworkflow

Sie können die Dokumentation schrittweise implementieren. Das Ziel ist nicht, alles auf einmal zu schreiben, sondern die Struktur frühzeitig aufzubauen und zu verbessern, wenn das Projekt reift.

Phase 1: Vor dem Schreiben eines Codes

1. Erstellen Sie eine Draft CITATION.cff-Datei.
2. Entwerfen Sie eine Skeleton Readme mit Projektzweck, Installationsplatzhalter und Lizenz.
3. Entscheiden Sie, ob die Hauptzielgruppe Benutzer, Entwickler, Betreuer oder alle drei sind.

Phase 2: Während der Entwicklung

1. Schreiben Sie Kommentare, während Sie codieren, insbesondere für algorithmische Entscheidungen.
2. Fügen Sie DocStrings für jede öffentliche Funktion und Klasse hinzu.
3. Richten Sie frühzeitig Sphinx oder Mkdocs ein, damit die Dokumentation neben dem Code erstellt wird.
4. Fügen Sie Beispiele hinzu, wenn Features stabil werden.

Phase 3: Nach der Entwicklung

1. Schreiben Sie eine Kurzanleitung.
2. Vervollständigen Sie die Readme mit Installations-, Verwendungs-, Lizenz- und Zitatanweisungen.
3. Schreiben Sie mindestens eine Anleitung für den häufigsten Anwendungsfall.
4. Erstellen oder aktualisieren Sie das DOI über Zenodo, Joss oder einen anderen geeigneten Publikationsweg.

Interne Links und verwandte Anleitungen

Zu verwandten Themen in wissenschaftlichen Simulations-Workflows:

• Best Practices für wissenschaftliche Python-Pakete — Python-spezifische Tooling und Dokumentation Struktur
• Kontinuierliche Integration für Forschungssoftware – CI / CD für automatisiertes Testen und Validieren.
• Fipy-Dokumentation lesen und verstehen – Praktische FIPY-Dokumentationsmuster.
• Reproduzierbare Forschungsworkflows: Docker und Conda – Reproduzierbarkeit der Umgebung.
• Best Practices für die Aufrechterhaltung des wissenschaftlichen Codes – Langfristige Projektpflege.

Zusammenfassung und nächste Schritte

Die Dokumentation verwandelt Code aus einem fragilen experimentellen Artefakt in ein dauerhaftes Forschungsgut. Das Diátaxis-Framework gibt Struktur. Die zehn einfachen Regeln geben eine praktische Checkliste. Vorlagen und Tools bieten einen schnellen Ausgangspunkt.

Beginnen Sie mit einem kleinen Schritt: Erstellen Sie eine CITATION.cff-Datei und fügen Sie eine Anleitung hinzu. Dies erleichtert das Zitieren und Guthaben der Software.

Fügen Sie dann eine Readme mit Installations-, Schnellstart-, Lizenz- und Dokumentationslinks hinzu. Dies ist das wirkungsvollste Dokument für die Benutzerfreundlichkeit.

Als nächstes dokumentieren Sie die API mit konsistenten DocStrings und richten Sie Sphinx oder Mkdocs ein. Dies hilft Benutzern und zukünftigen Betreuern zu verstehen, wie der Code funktioniert.

Schreiben Sie abschließend mindestens eine Anleitung für den häufigsten Anwendungsfall. Das ist oft die Seitenmitarbeiter.

Jede Dokumentation bringt Ihre Software der reproduzierbaren Forschung einen Schritt näher.

Referenzen und Weiterlesen

• Lee, B. D. (2018). Zehn einfache Regeln für die Dokumentation wissenschaftlicher Software. PLoS Computational Biology , 14 (12): e1006561. doi: 10.1371/journal.pcbi.1006561
• Software-Nachhaltigkeitsinstitut. Was sind Best Practices für die Dokumentation der Forschungssoftware? Quelle
• Procida, D. Diátaxis: Ein systematischer Ansatz zur Erstellung technischer Dokumentation. Quelle
• Wilson, G. et al. (2014). Best Practices für das wissenschaftliche Rechnen. PLoS Biology , 12 (1): e1001745. doi: 10.1371/journal.pbio.1001745
• Journal of Open Source Software. Quelle
• Lesen Sie die Dokumente. Quelle

Benötigen Sie Hilfe bei der Strukturierungsdokumentation für Ihr Simulationsprojekt?

Wenn Ihr Forschungsteam beim Aufbau automatisierter Dokumentations-Pipelines, beim Entwerfen einer diátaxis-konformen Dokumentationsstruktur oder beim Integrieren der Dokumentation in CI/CD-Workflows Hilfe benötigt, können unsere Experten für Computational Science helfen.

Kontaktieren Sie uns über unser Issue Tracking System, um die Dokumentationsanforderungen Ihres Projekts zu besprechen.