{"id":882,"date":"2026-07-30T12:23:24","date_gmt":"2026-07-30T12:23:24","guid":{"rendered":"https:\/\/matforge.org\/?p=882","raw":"https:\/\/matforge.org\/?p=882"},"modified":"2026-07-30T12:23:24","modified_gmt":"2026-07-30T12:23:24","slug":"research-software-documentation-practical-guide-scientists","status":"publish","type":"post","link":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/","title":{"rendered":"Forschungssoftware-Dokumentation: Ein praktischer Leitfaden f\u00fcr Wissenschaftler","raw":"Forschungssoftware-Dokumentation: Ein praktischer Leitfaden f\u00fcr Wissenschaftler"},"content":{"rendered":"<span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 7<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span><p>Sie haben gerade eine Simulations-Pipeline fertiggestellt. Ihre Ergebnisse sind Ver\u00f6ffentlichungsbereit. Ihr Code funktioniert. Warum m\u00fcssen Sie es also noch dokumentieren?<\/p>\n<p>Denn ohne Dokumentation ist Ihre Software schwerer zu zitieren, schwerer zu reproduzieren und schwerer zu warten. Mitarbeiter verstehen m\u00f6glicherweise nicht, wie sie ausgef\u00fchrt werden sollen. Zuk\u00fcnftige Studenten wissen m\u00f6glicherweise nicht, welche Konfigurationsdatei wichtig ist. Selbst Sie k\u00f6nnen wichtige Designentscheidungen nach mehreren Monaten vergessen.<\/p>\n<p>Die Dokumentation ist kein nettes Add-On f\u00fcr Forschungssoftware. Es ist die Br\u00fccke zwischen einem Arbeitsger\u00e4t und einem reproduzierbaren Forschungsgut. Sie m\u00fcssen kein technischer Redakteur sein, um es gut zu machen. Sie brauchen eine Struktur.<\/p>\n<h2>Schl\u00fcssel zum Mitnehmen<\/h2>\n<ul>\n<li>Die Dokumentation ist Teil der reproduzierbaren Forschung. Code ohne Dokumentation wird zu einer Black Box, die nur der urspr\u00fcngliche Autor pflegen kann.<\/li>\n<li>Vier Dokumentationstypen erf\u00fcllen vier verschiedene Benutzeranforderungen: Lernprogramme, Anleitungen zum Tun, Referenz zum Beschreiben und Erkl\u00e4rung f\u00fcr das Verst\u00e4ndnis.<\/li>\n<li>Das Di\u00e1taxis-Framework ist eine praktische M\u00f6glichkeit, Forschungssoftware-Dokumentation zu organisieren.<\/li>\n<li>Die zehn einfachen Regeln zur Dokumentation wissenschaftlicher Software bieten eine n\u00fctzliche Checkliste zum Schreiben besserer Dokumentation.<\/li>\n<li>Schablonen und Werkzeuge existieren bereits. Readme-Strukturen, <code>CITATION.cff<\/code>-Dateien, Sphinx, Mkdocs und Read the Docs machen den Prozess effizienter.<\/li>\n<\/ul>\n<h2>Warum Dokumentation wichtig ist<\/h2>\n<p>Forschungssoftware befindet sich zwischen Wissenschaft und Technik. Im Gegensatz zu herk\u00f6mmlichen Laborger\u00e4ten kann Software von jedem mit der richtigen Umgebung geteilt, ge\u00e4ndert, wiederverwendet und zitiert werden. Aber dieses Potenzial bedeutet wenig, wenn niemand versteht, wie die Software funktioniert.<\/p>\n<p>Die Eins\u00e4tze sind praktisch:<\/p>\n<ul>\n<li>Reproduzierbarkeit. Ohne Dokumentation k\u00f6nnen andere Forscher Ihre Arbeit nicht zuverl\u00e4ssig verifizieren oder wiederverwenden.<\/li>\n<li>Zitat. Software, die keine Anleitung und Gebrauchsanweisungen enth\u00e4lt, wird weniger wahrscheinlich gut belastet.<\/li>\n<li>Aufrechterhaltung Wenn ein Forscher ein Labor verl\u00e4sst, wird undokumentierter Code oft zu technischen Schulden f\u00fcr die n\u00e4chste Person.<\/li>\n<\/ul>\n<p>Eine gute Dokumentation erleichtert die Verwendung, Erweiterung, \u00dcberpr\u00fcfung und Aufbewahrung von Software. Es reduziert auch die Anzahl der wiederholten Fragen von Mitarbeitern und zuk\u00fcnftigen Benutzern.<\/p>\n<p>Dieser Leitfaden bietet Ihnen einen praktischen Rahmen und Vorlagen f\u00fcr die effektive Dokumentation der Forschungssoftware.<\/p>\n<h2>Das Di\u00e1taxis-Framework: Vier Arten von Dokumentation<\/h2>\n<p>Wenn Ihre Dokumentation derzeit in einer langen Readme-Datei lebt, f\u00fchlt sie sich m\u00f6glicherweise unorganisiert. Tutorials, Installationshinweise, API-Details, Theorie, Beispiele und Fehlerbehebung k\u00f6nnen leicht zusammengemischt werden.<\/p>\n<p>Das Di\u00e1taxis-Framework l\u00f6st dies, indem die Dokumentation in vier verschiedene Typen unterteilt wird. Jeder Typ dient einem anderen Benutzerbedarf.<\/p>\n<h3>1. Tutorials<\/h3>\n<p>Ein Tutorial ist lernorientiert. Es f\u00fchrt einen Anf\u00e4nger durch einen gef\u00fchrten Weg und hilft ihm, ein konkretes Ergebnis zu erzielen.<\/p>\n<p>Beispiel: \u201eFiPy f\u00fcr Ihre erste Phasenfeldsimulation einrichten.\u201c<\/p>\n<p>Ein Tutorial Antworten: Wie lerne ich, diese Software zu verwenden?<\/p>\n<h3>2. Anleitungen<\/h3>\n<p>Eine Anleitung ist handlungsorientiert. Es hilft jemandem, eine bestimmte Aufgabe zu erledigen, nachdem er die Grundlagen bereits verstanden hat.<\/p>\n<p>Beispiele sind:<\/p>\n<ul>\n<li>So f\u00fchren Sie eine Monte-Carlo-Simulation mit Fipy durch.<\/li>\n<li>So beheben Sie Konvergenzfehler.<\/li>\n<li>So exportieren Sie Simulationsergebnisse nach CSV.<\/li>\n<\/ul>\n<p>Eine Anleitung zur Anleitung: Wie erreiche ich eine bestimmte Aufgabe?<\/p>\n<h3>3. Referenz<\/h3>\n<p>Die Referenzdokumentation ist informationsorientiert. Es ist sachlich, neutral und vollst\u00e4ndig. Es beschreibt, was die Software liefert, ohne zu unterrichten oder zu \u00fcberzeugen.<\/p>\n<p>Beispiele sind:<\/p>\n<ul>\n<li>API-Dokumentation.<\/li>\n<li>Funktionssignaturen.<\/li>\n<li>Parameterspezifikationen.<\/li>\n<li>Klassendefinitionen.<\/li>\n<\/ul>\n<p>Referenzdokumentation Antworten: Was macht das?<\/p>\n<h3>4. Erkl\u00e4rung<\/h3>\n<p>Erkl\u00e4rung ist verst\u00e4ndnisorientiert. Es bietet Hintergrund-, Kontext-, Argumentations- und Designgr\u00fcnde.<\/p>\n<p>Beispiele sind:<\/p>\n<ul>\n<li>Warum der Solver implizite Zeitschritte verwendet.<\/li>\n<li>Das mathematische Modell hinter der Implementierung.<\/li>\n<li>Warum eine Mesh-Strategie einer anderen gegen\u00fcber gew\u00e4hlt wurde.<\/li>\n<\/ul>\n<p>Erkl\u00e4rung Antworten: Warum funktioniert das so?<\/p>\n<h2>Die zehn einfachen Regeln zur Dokumentation von Forschungssoftware<\/h2>\n<p>Die zehn einfachen Regeln zur Dokumentation wissenschaftlicher Software sind eine praktische Checkliste f\u00fcr die Dokumentationsqualit\u00e4t. Sie sind n\u00fctzlich, weil sie sich auf Gewohnheiten konzentrieren, die Forscher anwenden k\u00f6nnen, ohne eine vollst\u00e4ndige Dokumentationsabteilung aufzubauen.<\/p>\n<h3>Regel 1: Schreiben Sie Kommentare, w\u00e4hrend Sie codieren<\/h3>\n<p>Kommentare sollten die Ideen und Gr\u00fcnde f\u00fcr den Algorithmus erkl\u00e4ren und nicht nur das wiederholen, was der Code bereits sagt.<\/p>\n<pre><code class=\"language-python\"># Good: explains why this approach is used\n# Use implicit time stepping for stiff reaction terms to avoid\n# timestep restrictions that would make the simulation impractical.\nsolver = ImplicitTimeStepping(reaction_terms)\n\n# Bad: repeats the line without explaining intent\nsolver = ImplicitTimeStepping(reaction_terms)  # creates solver\n<\/code><\/pre>\n<h3>Regel 2: Viele Beispiele enthalten<\/h3>\n<p>Beispiele zeigen den Benutzern, wie die Software in der Praxis funktioniert. Geben Sie ausf\u00fchrbare Beispiele an, die den Hauptworkflow demonstrieren.<\/p>\n<p>Wenn die Dokumentation mit Beispielen zu voll wird, verschieben Sie sie in ein dediziertes <code>examples\/<\/code>-Verzeichnis und verkn\u00fcpfen Sie sie aus der Hauptdokumentation.<\/p>\n<h3>Regel 3: F\u00fcgen Sie eine Kurzanleitung hinzu<\/h3>\n<p>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.<\/p>\n<p>Ohne einen Schnellstart gehen viele Benutzer davon aus, dass die Software zu schwierig zu bedienen ist und vor dem Testen verlassen wird.<\/p>\n<h3>Regel 4: Schreiben Sie eine umfassende Readme<\/h3>\n<p>Angenommen, die Readme wird die einzige Dokumentation sein, die viele Benutzer lesen. Es sollte das Wesentliche klar abdecken.<\/p>\n<p>Eine starke Readme sollte enthalten:<\/p>\n<ul>\n<li>Eine kurze Projektbeschreibung.<\/li>\n<li>Installationsanleitungen und Abh\u00e4ngigkeiten.<\/li>\n<li>Ein Schnellstart-Beispiel.<\/li>\n<li>Lizenzinformationen.<\/li>\n<li>Zitieranweisungen.<\/li>\n<li>Ein Link zur vollst\u00e4ndigen Dokumentation.<\/li>\n<\/ul>\n<p>Readme-Vorlage:<\/p>\n<pre><code class=\"language-markdown\"># Project Name\n\nShort description: one sentence explaining what the software does.\n\n## Installation\n\n1. Clone this repository.\n2. Run `pip install -e .` or your preferred install command.\n3. Verify the installation:\n\n```python\nimport mypackage\nprint(mypackage.__version__)\n```\n\n## Quickstart\n\n```python\nfrom mypackage import MySimulator\n\nsim = MySimulator(config=\"default.yaml\")\nresults = sim.run()\n```\n\n## Documentation\n\nFull documentation: [Read the Docs link]\n\n## Citation\n\nPlease cite this software using the CITATION.cff file.\n\n## License\n\nMIT License\n<\/code><\/pre>\n<h3>Regel 5: F\u00fcgen Sie einen Hilfebefehl f\u00fcr CLIs ein<\/h3>\n<p>Wenn Ihre Software \u00fcber eine Befehlszeilenschnittstelle verf\u00fcgt, schlie\u00dfen Sie das Flag <code>--help<\/code> ein. Es sollte Befehle, erforderliche Argumente, optionale Parameter und Beispiele erl\u00e4utern.<\/p>\n<p>Python-Tools wie <code>argparse<\/code>  machen dies einfach.<\/p>\n<h3>Regel 6: Versionskontrolle Ihre Dokumentation<\/h3>\n<p>Bewahren Sie die Dokumentation neben dem Code in der Versionskontrolle auf. Benutzer \u00e4lterer Softwareversionen ben\u00f6tigen Zugriff auf diese Versionen.<\/p>\n<p>Verwenden Sie nach M\u00f6glichkeit versioniertes Dokumentations-Hosting, damit Benutzer zwischen den Versionen wechseln k\u00f6nnen.<\/p>\n<h3>Regel 7: Dokumentieren Sie Ihre API<\/h3>\n<p>Dokumentieren Sie \u00f6ffentliche Funktionen, Klassen, Argumente, R\u00fcckgabewerte und Ausnahmen. Verwenden Sie einen konsistenten DocString-Stil, damit automatisierte Tools lesbare API-Dokumentation generieren k\u00f6nnen.<\/p>\n<p>Beispiel:<\/p>\n<pre><code class=\"language-python\">def run_simulation(config_path, steps):\n    \"\"\"Run the simulation from a configuration file.\n\n    Args:\n        config_path: Path to the YAML configuration file.\n        steps: Number of time steps to run.\n\n    Returns:\n        Simulation results object with fields, metadata, and diagnostics.\n\n    Raises:\n        ValueError: If the configuration file is invalid.\n    \"\"\"\n    ...\n<\/code><\/pre>\n<h3>Regel 8: Verwenden Sie automatisierte Dokumentationstools<\/h3>\n<p>Schreiben Sie nicht alles manuell, wenn Tools einen Teil davon generieren k\u00f6nnen. Automatisierte Dokumentationswerkzeuge reduzieren sich wiederholende Arbeiten und halten die Dokumentation n\u00e4her am Code.<\/p>\n<p>N\u00fctzliche Werkzeuge sind:<\/p>\n<ul>\n<li>Sphinx f\u00fcr Python-Pakete mit komplexen APIs.<\/li>\n<li>Mkdocs f\u00fcr einfache markdown-basierte Dokumentationsseiten.<\/li>\n<li>Lesen Sie die Dokumente f\u00fcr das Hosting und die automatischen Dokumentationserstellungen.<\/li>\n<\/ul>\n<h3>Regel 9: Schreiben Sie umsetzbare Fehlermeldungen<\/h3>\n<p>Gute Fehlermeldungen sagen den Benutzern, was schief gelaufen ist, warum es passiert ist und wie man es behebt.<\/p>\n<pre><code class=\"language-python\"># Bad\nraise ValueError(\"Invalid input\")\n\n# Good\nraise ValueError(\n    f\"Input parameter 'temperature' must be between 0 and 3000 K. \"\n    f\"Received {temperature} K. Check your simulation config file.\"\n)\n<\/code><\/pre>\n<p>Dies spart Debug-Zeit und reduziert Supportanfragen.<\/p>\n<h3>Regel 10: Sagen Sie den Leuten, wie Sie Ihre Software zitieren sollen<\/h3>\n<p>Wenn Sie m\u00f6chten, dass Ihre Forschungssoftware Guthaben erh\u00e4lt, geben Sie Anweisungen zum Zitat. Schlie\u00dfen Sie eine doi-, bibtex- und <code>CITATION.cff<\/code>-Datei ein.<\/p>\n<p>Wenn die Software keine Zeitschriftenver\u00f6ffentlichung hat, verwenden Sie zenodo, um ein DOI f\u00fcr Releases zu pr\u00e4gen. Die Einreichung an das Journal of Open Source Software kann auch das Zitieren von Software erleichtern.<\/p>\n<h2>Dokumentationsvorlagen, die Sie heute verwenden k\u00f6nnen<\/h2>\n<h3>der Dokumentationsentscheidungsbaum<\/h3>\n<p>Stellen Sie vor dem Schreiben der Dokumentation drei Fragen:<\/p>\n<ol>\n<li>F\u00fcr wen ist es? Benutzer, Entwickler, Betreuer, Rezensenten oder Mitarbeiter?<\/li>\n<li>Was wollen sie? F\u00fchren Sie die Software aus, \u00e4ndern Sie sie, verstehen Sie das Modell oder zitieren Sie es?<\/li>\n<li>Welches Format entspricht dem Bedarf? Tutorial, Anleitung, Referenz, Erkl\u00e4rung, Inline-Kommentar oder API-Seite?<\/li>\n<\/ol>\n<p>Diese Fragen verhindern einen h\u00e4ufigen Fehler: Schreiben eines \u00fcberladenen Dokuments f\u00fcr jedes Publikum.<\/p>\n<h3>das Zitierdateiformat<\/h3>\n<p>Die <code>CITATION.cff<\/code>-Datei ist eine maschinenlesbare und menschenlesbare Datei f\u00fcr das Software-Zitat. Es kann enthalten:<\/p>\n<ul>\n<li>Softwarename und Version.<\/li>\n<li>Autoren und Zugeh\u00f6rigkeiten.<\/li>\n<li>DOI f\u00fcr die Software.<\/li>\n<li>BibTeX-Informationen.<\/li>\n<li>Repository-URL.<\/li>\n<\/ul>\n<p>In Verbindung mit einem zenodo doi wird <code>CITATION.cff<\/code> zu einem stabilen Zitationsdatensatz f\u00fcr Ihre Software.<\/p>\n<h3>Beispiel citation.cff Vorlage<\/h3>\n<pre><code class=\"language-yaml\">cff-version: 1.2.0\nmessage: \"If you use this software, please cite it as below.\"\ntitle: \"Project Name\"\nversion: \"1.0.0\"\ndoi: \"10.5281\/zenodo.xxxxxxx\"\nauthors:\n  - family-names: \"Surname\"\n    given-names: \"First Name\"\n    affiliation: \"Research Institution\"\nrepository-code: \"https:\/\/github.com\/username\/project-name\"\nlicense: \"MIT\"\n<\/code><\/pre>\n<h2>Handwerkszeug<\/h2>\n<table class=\"custom-table\">\n<tbody>\n<tr>\n<th>Werkzeug<\/th>\n<th>Zweck<\/th>\n<th>am besten f\u00fcr<\/th>\n<\/tr>\n<tr>\n<td>Sphinx<\/td>\n<td>Generiert Dokumentation aus DocStrings und RestructuredText oder Markdown<\/td>\n<td>Python-Pakete mit komplexen APIs<\/td>\n<\/tr>\n<tr>\n<td>mkdocs<\/td>\n<td>Erstellt markdown-basierte Dokumentationsseiten<\/td>\n<td>Leichte Projekte, die eine einfache Dokumentationsseite ben\u00f6tigen<\/td>\n<\/tr>\n<tr>\n<td>Lesen Sie die Dokumente<\/td>\n<td>Hosts und Auto-Builds versionierte Dokumentation<\/td>\n<td>Projekte, die eine automatische Dokumentationsbereitstellung ben\u00f6tigen<\/td>\n<\/tr>\n<tr>\n<td>Sauerstoff<\/td>\n<td>Generiert Dokumentation f\u00fcr C-, C++-, Python- und gemischtsprachige Projekte<\/td>\n<td>Projekte mit C++ oder gemischten wissenschaftlichen Codebasen<\/td>\n<\/tr>\n<tr>\n<td>Zenodo<\/td>\n<td>Mints DOIs und archiviert Software-Releases<\/td>\n<td>Langzeitzitat und Reproduzierbarkeit<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>h\u00e4ufige Fehler und wie man sie vermeidet<\/h2>\n<h3>Fehler 1: Alles als Readme behandeln<\/h3>\n<p>Eine Readme kann nicht jeden Job gut machen. Wenn Sie Tutorials, Referenzen, Erkl\u00e4rungen, API-Details und Fehlerbehebung in einer Datei kombinieren, haben Benutzer Schwierigkeiten, das zu finden, was sie ben\u00f6tigen.<\/p>\n<p>Trennen Sie die Dokumentation nach Verwendungszweck der Di\u00e1taxis-Quadranten.<\/p>\n<h3>Fehler 2: Erkl\u00e4rung in Tutorials schreiben<\/h3>\n<p>Tutorials sollten kurz, praktisch und linear sein. Wenn ein Anf\u00e4nger das mathematische Modell vor der Verwendung der Software verstehen muss, legen Sie diese Erkl\u00e4rung auf eine separate Seite und verlinken Sie darauf.<\/p>\n<h3>Fehler 3: Nicht versionskontrollierende Dokumentation<\/h3>\n<p>Wenn Sie in Version 2.0 einen Standardparameter \u00e4ndern, ben\u00f6tigen Benutzer der Version 1.5 die alte Dokumentation. Versionierte Dokumente verhindern Verwirrung und machen \u00e4ltere Releases nutzbarer.<\/p>\n<h3>Fehler 4: Angenommen, Sie werden sich an alles erinnern<\/h3>\n<p>Sie k\u00f6nnen sich sechs Monate sp\u00e4ter nicht an Ihre Designentscheidungen erinnern. Kommentare und Erkl\u00e4rungsseiten dienen als Labornotiz f\u00fcr Ihre Implementierungsentscheidungen.<\/p>\n<h3>Fehler 5: Zitatanweisungen vergessen<\/h3>\n<p>Software ohne Zitationsberatung erh\u00e4lt oft weniger Guthaben. F\u00fcgen Sie eine doi-, bibtex- und <code>CITATION.cff<\/code>-Datei ein, damit die Benutzer genau wissen, wie Sie Ihre Arbeit zitieren k\u00f6nnen.<\/p>\n<h2>Ein praktischer Dokumentationsworkflow<\/h2>\n<p>Sie k\u00f6nnen die Dokumentation schrittweise implementieren. Das Ziel ist nicht, alles auf einmal zu schreiben, sondern die Struktur fr\u00fchzeitig aufzubauen und zu verbessern, wenn das Projekt reift.<\/p>\n<h3>Phase 1: Vor dem Schreiben eines Codes<\/h3>\n<ol>\n<li>Erstellen Sie eine Draft <code>CITATION.cff<\/code>-Datei.<\/li>\n<li>Entwerfen Sie eine Skeleton Readme mit Projektzweck, Installationsplatzhalter und Lizenz.<\/li>\n<li>Entscheiden Sie, ob die Hauptzielgruppe Benutzer, Entwickler, Betreuer oder alle drei sind.<\/li>\n<\/ol>\n<h3>Phase 2: W\u00e4hrend der Entwicklung<\/h3>\n<ol>\n<li>Schreiben Sie Kommentare, w\u00e4hrend Sie codieren, insbesondere f\u00fcr algorithmische Entscheidungen.<\/li>\n<li>F\u00fcgen Sie DocStrings f\u00fcr jede \u00f6ffentliche Funktion und Klasse hinzu.<\/li>\n<li>Richten Sie fr\u00fchzeitig Sphinx oder Mkdocs ein, damit die Dokumentation neben dem Code erstellt wird.<\/li>\n<li>F\u00fcgen Sie Beispiele hinzu, wenn Features stabil werden.<\/li>\n<\/ol>\n<h3>Phase 3: Nach der Entwicklung<\/h3>\n<ol>\n<li>Schreiben Sie eine Kurzanleitung.<\/li>\n<li>Vervollst\u00e4ndigen Sie die Readme mit Installations-, Verwendungs-, Lizenz- und Zitatanweisungen.<\/li>\n<li>Schreiben Sie mindestens eine Anleitung f\u00fcr den h\u00e4ufigsten Anwendungsfall.<\/li>\n<li>Erstellen oder aktualisieren Sie das DOI \u00fcber Zenodo, Joss oder einen anderen geeigneten Publikationsweg.<\/li>\n<\/ol>\n<h2>Interne Links und verwandte Anleitungen<\/h2>\n<p>Zu verwandten Themen in wissenschaftlichen Simulations-Workflows:<\/p>\n<ul>\n<li><a href=\"https:\/\/matforge.org\/documentation-best-practices-scientific-python-packages\/\">Best Practices f\u00fcr wissenschaftliche Python-Pakete<\/a> \u2014 Python-spezifische Tooling und Dokumentation Struktur<\/li>\n<li><a href=\"https:\/\/matforge.org\/continuous-integration-research-software-automated-testing-validation\/\"> Kontinuierliche Integration f\u00fcr Forschungssoftware <\/a> &#8211; CI \/ CD f\u00fcr automatisiertes Testen und Validieren.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reading-and-understanding-fipy-documentation\/\">Fipy-Dokumentation lesen und verstehen <\/a> &#8211; Praktische FIPY-Dokumentationsmuster.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reproducible-research-workflows-docker-and-conda-for-simulation-projects\/\">Reproduzierbare Forschungsworkflows: Docker und Conda <\/a> &#8211; Reproduzierbarkeit der Umgebung.<\/li>\n<li><a href=\"https:\/\/matforge.org\/best-practices-for-maintaining-scientific-code\/\"> Best Practices f\u00fcr die Aufrechterhaltung des wissenschaftlichen Codes <\/a> &#8211; Langfristige Projektpflege.<\/li>\n<\/ul>\n<h2>Zusammenfassung und n\u00e4chste Schritte<\/h2>\n<p>Die Dokumentation verwandelt Code aus einem fragilen experimentellen Artefakt in ein dauerhaftes Forschungsgut. Das Di\u00e1taxis-Framework gibt Struktur. Die zehn einfachen Regeln geben eine praktische Checkliste. Vorlagen und Tools bieten einen schnellen Ausgangspunkt.<\/p>\n<p>Beginnen Sie mit einem kleinen Schritt: Erstellen Sie eine <code>CITATION.cff<\/code>-Datei und f\u00fcgen Sie eine Anleitung hinzu. Dies erleichtert das Zitieren und Guthaben der Software.<\/p>\n<p>F\u00fcgen Sie dann eine Readme mit Installations-, Schnellstart-, Lizenz- und Dokumentationslinks hinzu. Dies ist das wirkungsvollste Dokument f\u00fcr die Benutzerfreundlichkeit.<\/p>\n<p>Als n\u00e4chstes dokumentieren Sie die API mit konsistenten DocStrings und richten Sie Sphinx oder Mkdocs ein. Dies hilft Benutzern und zuk\u00fcnftigen Betreuern zu verstehen, wie der Code funktioniert.<\/p>\n<p>Schreiben Sie abschlie\u00dfend mindestens eine Anleitung f\u00fcr den h\u00e4ufigsten Anwendungsfall. Das ist oft die Seitenmitarbeiter.<\/p>\n<p>Jede Dokumentation bringt Ihre Software der reproduzierbaren Forschung einen Schritt n\u00e4her.<\/p>\n<h2>Referenzen und Weiterlesen<\/h2>\n<ul>\n<li>Lee, B. D. (2018). Zehn einfache Regeln f\u00fcr die Dokumentation wissenschaftlicher Software. <em> PLoS Computational Biology <\/em>, 14 (12): e1006561. <a href=\"https:\/\/doi.org\/10.1371\/journal.pcbi.1006561\"> doi: 10.1371\/journal.pcbi.1006561 <\/a><\/li>\n<li>Software-Nachhaltigkeitsinstitut. Was sind Best Practices f\u00fcr die Dokumentation der Forschungssoftware? <a href=\"https:\/\/www.software.ac.uk\/blog\/what-are-best-practices-research-software-documentation\"> Quelle <\/a><\/li>\n<li>Procida, D. Di\u00e1taxis: Ein systematischer Ansatz zur Erstellung technischer Dokumentation. <a href=\"https:\/\/diataxis.fr\/\"> Quelle <\/a><\/li>\n<li>Wilson, G. et al. (2014). Best Practices f\u00fcr das wissenschaftliche Rechnen. <em> PLoS Biology <\/em>, 12 (1): e1001745. <a href=\"https:\/\/doi.org\/10.1371\/journal.pbio.1001745\"> doi: 10.1371\/journal.pbio.1001745 <\/a><\/li>\n<li>Journal of Open Source Software. <a href=\"https:\/\/joss.theoj.org\/\"> Quelle <\/a><\/li>\n<li>Lesen Sie die Dokumente. <a href=\"https:\/\/readthedocs.org\/\"> Quelle <\/a><\/li>\n<\/ul>\n<h2>Ben\u00f6tigen Sie Hilfe bei der Strukturierungsdokumentation f\u00fcr Ihr Simulationsprojekt?<\/h2>\n<p>Wenn Ihr Forschungsteam beim Aufbau automatisierter Dokumentations-Pipelines, beim Entwerfen einer di\u00e1taxis-konformen Dokumentationsstruktur oder beim Integrieren der Dokumentation in CI\/CD-Workflows Hilfe ben\u00f6tigt, k\u00f6nnen unsere Experten f\u00fcr Computational Science helfen.<\/p>\n<p>Kontaktieren Sie uns \u00fcber unser <a href=\"https:\/\/matforge.org\/category\/issue-tracking-tickets-technical-requests\/\">Issue Tracking System<\/a>, um die Dokumentationsanforderungen Ihres Projekts zu besprechen.<\/p>\n","protected":false,"raw":"<p>Sie haben gerade eine Simulations-Pipeline fertiggestellt. Ihre Ergebnisse sind Ver\u00f6ffentlichungsbereit. Ihr Code funktioniert. Warum m\u00fcssen Sie es also noch dokumentieren?<\/p>\n<p>Denn ohne Dokumentation ist Ihre Software schwerer zu zitieren, schwerer zu reproduzieren und schwerer zu warten. Mitarbeiter verstehen m\u00f6glicherweise nicht, wie sie ausgef\u00fchrt werden sollen. Zuk\u00fcnftige Studenten wissen m\u00f6glicherweise nicht, welche Konfigurationsdatei wichtig ist. Selbst Sie k\u00f6nnen wichtige Designentscheidungen nach mehreren Monaten vergessen.<\/p>\n<p>Die Dokumentation ist kein nettes Add-On f\u00fcr Forschungssoftware. Es ist die Br\u00fccke zwischen einem Arbeitsger\u00e4t und einem reproduzierbaren Forschungsgut. Sie m\u00fcssen kein technischer Redakteur sein, um es gut zu machen. Sie brauchen eine Struktur.<\/p>\n<h2>Schl\u00fcssel zum Mitnehmen<\/h2>\n<ul>\n<li>Die Dokumentation ist Teil der reproduzierbaren Forschung. Code ohne Dokumentation wird zu einer Black Box, die nur der urspr\u00fcngliche Autor pflegen kann.<\/li>\n<li>Vier Dokumentationstypen erf\u00fcllen vier verschiedene Benutzeranforderungen: Lernprogramme, Anleitungen zum Tun, Referenz zum Beschreiben und Erkl\u00e4rung f\u00fcr das Verst\u00e4ndnis.<\/li>\n<li>Das Di\u00e1taxis-Framework ist eine praktische M\u00f6glichkeit, Forschungssoftware-Dokumentation zu organisieren.<\/li>\n<li>Die zehn einfachen Regeln zur Dokumentation wissenschaftlicher Software bieten eine n\u00fctzliche Checkliste zum Schreiben besserer Dokumentation.<\/li>\n<li>Schablonen und Werkzeuge existieren bereits. Readme-Strukturen, <code>CITATION.cff<\/code>-Dateien, Sphinx, Mkdocs und Read the Docs machen den Prozess effizienter.<\/li>\n<\/ul>\n<h2>Warum Dokumentation wichtig ist<\/h2>\n<p>Forschungssoftware befindet sich zwischen Wissenschaft und Technik. Im Gegensatz zu herk\u00f6mmlichen Laborger\u00e4ten kann Software von jedem mit der richtigen Umgebung geteilt, ge\u00e4ndert, wiederverwendet und zitiert werden. Aber dieses Potenzial bedeutet wenig, wenn niemand versteht, wie die Software funktioniert.<\/p>\n<p>Die Eins\u00e4tze sind praktisch:<\/p>\n<ul>\n<li>Reproduzierbarkeit. Ohne Dokumentation k\u00f6nnen andere Forscher Ihre Arbeit nicht zuverl\u00e4ssig verifizieren oder wiederverwenden.<\/li>\n<li>Zitat. Software, die keine Anleitung und Gebrauchsanweisungen enth\u00e4lt, wird weniger wahrscheinlich gut belastet.<\/li>\n<li>Aufrechterhaltung Wenn ein Forscher ein Labor verl\u00e4sst, wird undokumentierter Code oft zu technischen Schulden f\u00fcr die n\u00e4chste Person.<\/li>\n<\/ul>\n<p>Eine gute Dokumentation erleichtert die Verwendung, Erweiterung, \u00dcberpr\u00fcfung und Aufbewahrung von Software. Es reduziert auch die Anzahl der wiederholten Fragen von Mitarbeitern und zuk\u00fcnftigen Benutzern.<\/p>\n<p>Dieser Leitfaden bietet Ihnen einen praktischen Rahmen und Vorlagen f\u00fcr die effektive Dokumentation der Forschungssoftware.<\/p>\n<h2>Das Di\u00e1taxis-Framework: Vier Arten von Dokumentation<\/h2>\n<p>Wenn Ihre Dokumentation derzeit in einer langen Readme-Datei lebt, f\u00fchlt sie sich m\u00f6glicherweise unorganisiert. Tutorials, Installationshinweise, API-Details, Theorie, Beispiele und Fehlerbehebung k\u00f6nnen leicht zusammengemischt werden.<\/p>\n<p>Das Di\u00e1taxis-Framework l\u00f6st dies, indem die Dokumentation in vier verschiedene Typen unterteilt wird. Jeder Typ dient einem anderen Benutzerbedarf.<\/p>\n<h3>1. Tutorials<\/h3>\n<p>Ein Tutorial ist lernorientiert. Es f\u00fchrt einen Anf\u00e4nger durch einen gef\u00fchrten Weg und hilft ihm, ein konkretes Ergebnis zu erzielen.<\/p>\n<p>Beispiel: \u201eFiPy f\u00fcr Ihre erste Phasenfeldsimulation einrichten.\u201c<\/p>\n<p>Ein Tutorial Antworten: Wie lerne ich, diese Software zu verwenden?<\/p>\n<h3>2. Anleitungen<\/h3>\n<p>Eine Anleitung ist handlungsorientiert. Es hilft jemandem, eine bestimmte Aufgabe zu erledigen, nachdem er die Grundlagen bereits verstanden hat.<\/p>\n<p>Beispiele sind:<\/p>\n<ul>\n<li>So f\u00fchren Sie eine Monte-Carlo-Simulation mit Fipy durch.<\/li>\n<li>So beheben Sie Konvergenzfehler.<\/li>\n<li>So exportieren Sie Simulationsergebnisse nach CSV.<\/li>\n<\/ul>\n<p>Eine Anleitung zur Anleitung: Wie erreiche ich eine bestimmte Aufgabe?<\/p>\n<h3>3. Referenz<\/h3>\n<p>Die Referenzdokumentation ist informationsorientiert. Es ist sachlich, neutral und vollst\u00e4ndig. Es beschreibt, was die Software liefert, ohne zu unterrichten oder zu \u00fcberzeugen.<\/p>\n<p>Beispiele sind:<\/p>\n<ul>\n<li>API-Dokumentation.<\/li>\n<li>Funktionssignaturen.<\/li>\n<li>Parameterspezifikationen.<\/li>\n<li>Klassendefinitionen.<\/li>\n<\/ul>\n<p>Referenzdokumentation Antworten: Was macht das?<\/p>\n<h3>4. Erkl\u00e4rung<\/h3>\n<p>Erkl\u00e4rung ist verst\u00e4ndnisorientiert. Es bietet Hintergrund-, Kontext-, Argumentations- und Designgr\u00fcnde.<\/p>\n<p>Beispiele sind:<\/p>\n<ul>\n<li>Warum der Solver implizite Zeitschritte verwendet.<\/li>\n<li>Das mathematische Modell hinter der Implementierung.<\/li>\n<li>Warum eine Mesh-Strategie einer anderen gegen\u00fcber gew\u00e4hlt wurde.<\/li>\n<\/ul>\n<p>Erkl\u00e4rung Antworten: Warum funktioniert das so?<\/p>\n<h2>Die zehn einfachen Regeln zur Dokumentation von Forschungssoftware<\/h2>\n<p>Die zehn einfachen Regeln zur Dokumentation wissenschaftlicher Software sind eine praktische Checkliste f\u00fcr die Dokumentationsqualit\u00e4t. Sie sind n\u00fctzlich, weil sie sich auf Gewohnheiten konzentrieren, die Forscher anwenden k\u00f6nnen, ohne eine vollst\u00e4ndige Dokumentationsabteilung aufzubauen.<\/p>\n<h3>Regel 1: Schreiben Sie Kommentare, w\u00e4hrend Sie codieren<\/h3>\n<p>Kommentare sollten die Ideen und Gr\u00fcnde f\u00fcr den Algorithmus erkl\u00e4ren und nicht nur das wiederholen, was der Code bereits sagt.<\/p>\n<pre><code class=\"language-python\"># Good: explains why this approach is used\n# Use implicit time stepping for stiff reaction terms to avoid\n# timestep restrictions that would make the simulation impractical.\nsolver = ImplicitTimeStepping(reaction_terms)\n\n# Bad: repeats the line without explaining intent\nsolver = ImplicitTimeStepping(reaction_terms)  # creates solver\n<\/code><\/pre>\n<h3>Regel 2: Viele Beispiele enthalten<\/h3>\n<p>Beispiele zeigen den Benutzern, wie die Software in der Praxis funktioniert. Geben Sie ausf\u00fchrbare Beispiele an, die den Hauptworkflow demonstrieren.<\/p>\n<p>Wenn die Dokumentation mit Beispielen zu voll wird, verschieben Sie sie in ein dediziertes <code>examples\/<\/code>-Verzeichnis und verkn\u00fcpfen Sie sie aus der Hauptdokumentation.<\/p>\n<h3>Regel 3: F\u00fcgen Sie eine Kurzanleitung hinzu<\/h3>\n<p>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.<\/p>\n<p>Ohne einen Schnellstart gehen viele Benutzer davon aus, dass die Software zu schwierig zu bedienen ist und vor dem Testen verlassen wird.<\/p>\n<h3>Regel 4: Schreiben Sie eine umfassende Readme<\/h3>\n<p>Angenommen, die Readme wird die einzige Dokumentation sein, die viele Benutzer lesen. Es sollte das Wesentliche klar abdecken.<\/p>\n<p>Eine starke Readme sollte enthalten:<\/p>\n<ul>\n<li>Eine kurze Projektbeschreibung.<\/li>\n<li>Installationsanleitungen und Abh\u00e4ngigkeiten.<\/li>\n<li>Ein Schnellstart-Beispiel.<\/li>\n<li>Lizenzinformationen.<\/li>\n<li>Zitieranweisungen.<\/li>\n<li>Ein Link zur vollst\u00e4ndigen Dokumentation.<\/li>\n<\/ul>\n<p>Readme-Vorlage:<\/p>\n<pre><code class=\"language-markdown\"># Project Name\n\nShort description: one sentence explaining what the software does.\n\n## Installation\n\n1. Clone this repository.\n2. Run `pip install -e .` or your preferred install command.\n3. Verify the installation:\n\n```python\nimport mypackage\nprint(mypackage.__version__)\n```\n\n## Quickstart\n\n```python\nfrom mypackage import MySimulator\n\nsim = MySimulator(config=\"default.yaml\")\nresults = sim.run()\n```\n\n## Documentation\n\nFull documentation: [Read the Docs link]\n\n## Citation\n\nPlease cite this software using the CITATION.cff file.\n\n## License\n\nMIT License\n<\/code><\/pre>\n<h3>Regel 5: F\u00fcgen Sie einen Hilfebefehl f\u00fcr CLIs ein<\/h3>\n<p>Wenn Ihre Software \u00fcber eine Befehlszeilenschnittstelle verf\u00fcgt, schlie\u00dfen Sie das Flag <code>--help<\/code> ein. Es sollte Befehle, erforderliche Argumente, optionale Parameter und Beispiele erl\u00e4utern.<\/p>\n<p>Python-Tools wie <code>argparse<\/code>  machen dies einfach.<\/p>\n<h3>Regel 6: Versionskontrolle Ihre Dokumentation<\/h3>\n<p>Bewahren Sie die Dokumentation neben dem Code in der Versionskontrolle auf. Benutzer \u00e4lterer Softwareversionen ben\u00f6tigen Zugriff auf diese Versionen.<\/p>\n<p>Verwenden Sie nach M\u00f6glichkeit versioniertes Dokumentations-Hosting, damit Benutzer zwischen den Versionen wechseln k\u00f6nnen.<\/p>\n<h3>Regel 7: Dokumentieren Sie Ihre API<\/h3>\n<p>Dokumentieren Sie \u00f6ffentliche Funktionen, Klassen, Argumente, R\u00fcckgabewerte und Ausnahmen. Verwenden Sie einen konsistenten DocString-Stil, damit automatisierte Tools lesbare API-Dokumentation generieren k\u00f6nnen.<\/p>\n<p>Beispiel:<\/p>\n<pre><code class=\"language-python\">def run_simulation(config_path, steps):\n    \"\"\"Run the simulation from a configuration file.\n\n    Args:\n        config_path: Path to the YAML configuration file.\n        steps: Number of time steps to run.\n\n    Returns:\n        Simulation results object with fields, metadata, and diagnostics.\n\n    Raises:\n        ValueError: If the configuration file is invalid.\n    \"\"\"\n    ...\n<\/code><\/pre>\n<h3>Regel 8: Verwenden Sie automatisierte Dokumentationstools<\/h3>\n<p>Schreiben Sie nicht alles manuell, wenn Tools einen Teil davon generieren k\u00f6nnen. Automatisierte Dokumentationswerkzeuge reduzieren sich wiederholende Arbeiten und halten die Dokumentation n\u00e4her am Code.<\/p>\n<p>N\u00fctzliche Werkzeuge sind:<\/p>\n<ul>\n<li>Sphinx f\u00fcr Python-Pakete mit komplexen APIs.<\/li>\n<li>Mkdocs f\u00fcr einfache markdown-basierte Dokumentationsseiten.<\/li>\n<li>Lesen Sie die Dokumente f\u00fcr das Hosting und die automatischen Dokumentationserstellungen.<\/li>\n<\/ul>\n<h3>Regel 9: Schreiben Sie umsetzbare Fehlermeldungen<\/h3>\n<p>Gute Fehlermeldungen sagen den Benutzern, was schief gelaufen ist, warum es passiert ist und wie man es behebt.<\/p>\n<pre><code class=\"language-python\"># Bad\nraise ValueError(\"Invalid input\")\n\n# Good\nraise ValueError(\n    f\"Input parameter 'temperature' must be between 0 and 3000 K. \"\n    f\"Received {temperature} K. Check your simulation config file.\"\n)\n<\/code><\/pre>\n<p>Dies spart Debug-Zeit und reduziert Supportanfragen.<\/p>\n<h3>Regel 10: Sagen Sie den Leuten, wie Sie Ihre Software zitieren sollen<\/h3>\n<p>Wenn Sie m\u00f6chten, dass Ihre Forschungssoftware Guthaben erh\u00e4lt, geben Sie Anweisungen zum Zitat. Schlie\u00dfen Sie eine doi-, bibtex- und <code>CITATION.cff<\/code>-Datei ein.<\/p>\n<p>Wenn die Software keine Zeitschriftenver\u00f6ffentlichung hat, verwenden Sie zenodo, um ein DOI f\u00fcr Releases zu pr\u00e4gen. Die Einreichung an das Journal of Open Source Software kann auch das Zitieren von Software erleichtern.<\/p>\n<h2>Dokumentationsvorlagen, die Sie heute verwenden k\u00f6nnen<\/h2>\n<h3>der Dokumentationsentscheidungsbaum<\/h3>\n<p>Stellen Sie vor dem Schreiben der Dokumentation drei Fragen:<\/p>\n<ol>\n<li>F\u00fcr wen ist es? Benutzer, Entwickler, Betreuer, Rezensenten oder Mitarbeiter?<\/li>\n<li>Was wollen sie? F\u00fchren Sie die Software aus, \u00e4ndern Sie sie, verstehen Sie das Modell oder zitieren Sie es?<\/li>\n<li>Welches Format entspricht dem Bedarf? Tutorial, Anleitung, Referenz, Erkl\u00e4rung, Inline-Kommentar oder API-Seite?<\/li>\n<\/ol>\n<p>Diese Fragen verhindern einen h\u00e4ufigen Fehler: Schreiben eines \u00fcberladenen Dokuments f\u00fcr jedes Publikum.<\/p>\n<h3>das Zitierdateiformat<\/h3>\n<p>Die <code>CITATION.cff<\/code>-Datei ist eine maschinenlesbare und menschenlesbare Datei f\u00fcr das Software-Zitat. Es kann enthalten:<\/p>\n<ul>\n<li>Softwarename und Version.<\/li>\n<li>Autoren und Zugeh\u00f6rigkeiten.<\/li>\n<li>DOI f\u00fcr die Software.<\/li>\n<li>BibTeX-Informationen.<\/li>\n<li>Repository-URL.<\/li>\n<\/ul>\n<p>In Verbindung mit einem zenodo doi wird <code>CITATION.cff<\/code> zu einem stabilen Zitationsdatensatz f\u00fcr Ihre Software.<\/p>\n<h3>Beispiel citation.cff Vorlage<\/h3>\n<pre><code class=\"language-yaml\">cff-version: 1.2.0\nmessage: \"If you use this software, please cite it as below.\"\ntitle: \"Project Name\"\nversion: \"1.0.0\"\ndoi: \"10.5281\/zenodo.xxxxxxx\"\nauthors:\n  - family-names: \"Surname\"\n    given-names: \"First Name\"\n    affiliation: \"Research Institution\"\nrepository-code: \"https:\/\/github.com\/username\/project-name\"\nlicense: \"MIT\"\n<\/code><\/pre>\n<h2>Handwerkszeug<\/h2>\n<table class=\"custom-table\">\n<tbody><tr>\n<th>Werkzeug<\/th>\n<th>Zweck<\/th>\n<th>am besten f\u00fcr<\/th>\n<\/tr>\n<tr>\n<td>Sphinx<\/td>\n<td>Generiert Dokumentation aus DocStrings und RestructuredText oder Markdown<\/td>\n<td>Python-Pakete mit komplexen APIs<\/td>\n<\/tr>\n<tr>\n<td>mkdocs<\/td>\n<td>Erstellt markdown-basierte Dokumentationsseiten<\/td>\n<td>Leichte Projekte, die eine einfache Dokumentationsseite ben\u00f6tigen<\/td>\n<\/tr>\n<tr>\n<td>Lesen Sie die Dokumente<\/td>\n<td>Hosts und Auto-Builds versionierte Dokumentation<\/td>\n<td>Projekte, die eine automatische Dokumentationsbereitstellung ben\u00f6tigen<\/td>\n<\/tr>\n<tr>\n<td>Sauerstoff<\/td>\n<td>Generiert Dokumentation f\u00fcr C-, C++-, Python- und gemischtsprachige Projekte<\/td>\n<td>Projekte mit C++ oder gemischten wissenschaftlichen Codebasen<\/td>\n<\/tr>\n<tr>\n<td>Zenodo<\/td>\n<td>Mints DOIs und archiviert Software-Releases<\/td>\n<td>Langzeitzitat und Reproduzierbarkeit<\/td>\n<\/tr>\n<\/tbody><\/table>\n<h2>h\u00e4ufige Fehler und wie man sie vermeidet<\/h2>\n<h3>Fehler 1: Alles als Readme behandeln<\/h3>\n<p>Eine Readme kann nicht jeden Job gut machen. Wenn Sie Tutorials, Referenzen, Erkl\u00e4rungen, API-Details und Fehlerbehebung in einer Datei kombinieren, haben Benutzer Schwierigkeiten, das zu finden, was sie ben\u00f6tigen.<\/p>\n<p>Trennen Sie die Dokumentation nach Verwendungszweck der Di\u00e1taxis-Quadranten.<\/p>\n<h3>Fehler 2: Erkl\u00e4rung in Tutorials schreiben<\/h3>\n<p>Tutorials sollten kurz, praktisch und linear sein. Wenn ein Anf\u00e4nger das mathematische Modell vor der Verwendung der Software verstehen muss, legen Sie diese Erkl\u00e4rung auf eine separate Seite und verlinken Sie darauf.<\/p>\n<h3>Fehler 3: Nicht versionskontrollierende Dokumentation<\/h3>\n<p>Wenn Sie in Version 2.0 einen Standardparameter \u00e4ndern, ben\u00f6tigen Benutzer der Version 1.5 die alte Dokumentation. Versionierte Dokumente verhindern Verwirrung und machen \u00e4ltere Releases nutzbarer.<\/p>\n<h3>Fehler 4: Angenommen, Sie werden sich an alles erinnern<\/h3>\n<p>Sie k\u00f6nnen sich sechs Monate sp\u00e4ter nicht an Ihre Designentscheidungen erinnern. Kommentare und Erkl\u00e4rungsseiten dienen als Labornotiz f\u00fcr Ihre Implementierungsentscheidungen.<\/p>\n<h3>Fehler 5: Zitatanweisungen vergessen<\/h3>\n<p>Software ohne Zitationsberatung erh\u00e4lt oft weniger Guthaben. F\u00fcgen Sie eine doi-, bibtex- und <code>CITATION.cff<\/code>-Datei ein, damit die Benutzer genau wissen, wie Sie Ihre Arbeit zitieren k\u00f6nnen.<\/p>\n<h2>Ein praktischer Dokumentationsworkflow<\/h2>\n<p>Sie k\u00f6nnen die Dokumentation schrittweise implementieren. Das Ziel ist nicht, alles auf einmal zu schreiben, sondern die Struktur fr\u00fchzeitig aufzubauen und zu verbessern, wenn das Projekt reift.<\/p>\n<h3>Phase 1: Vor dem Schreiben eines Codes<\/h3>\n<ol>\n<li>Erstellen Sie eine Draft <code>CITATION.cff<\/code>-Datei.<\/li>\n<li>Entwerfen Sie eine Skeleton Readme mit Projektzweck, Installationsplatzhalter und Lizenz.<\/li>\n<li>Entscheiden Sie, ob die Hauptzielgruppe Benutzer, Entwickler, Betreuer oder alle drei sind.<\/li>\n<\/ol>\n<h3>Phase 2: W\u00e4hrend der Entwicklung<\/h3>\n<ol>\n<li>Schreiben Sie Kommentare, w\u00e4hrend Sie codieren, insbesondere f\u00fcr algorithmische Entscheidungen.<\/li>\n<li>F\u00fcgen Sie DocStrings f\u00fcr jede \u00f6ffentliche Funktion und Klasse hinzu.<\/li>\n<li>Richten Sie fr\u00fchzeitig Sphinx oder Mkdocs ein, damit die Dokumentation neben dem Code erstellt wird.<\/li>\n<li>F\u00fcgen Sie Beispiele hinzu, wenn Features stabil werden.<\/li>\n<\/ol>\n<h3>Phase 3: Nach der Entwicklung<\/h3>\n<ol>\n<li>Schreiben Sie eine Kurzanleitung.<\/li>\n<li>Vervollst\u00e4ndigen Sie die Readme mit Installations-, Verwendungs-, Lizenz- und Zitatanweisungen.<\/li>\n<li>Schreiben Sie mindestens eine Anleitung f\u00fcr den h\u00e4ufigsten Anwendungsfall.<\/li>\n<li>Erstellen oder aktualisieren Sie das DOI \u00fcber Zenodo, Joss oder einen anderen geeigneten Publikationsweg.<\/li>\n<\/ol>\n<h2>Interne Links und verwandte Anleitungen<\/h2>\n<p>Zu verwandten Themen in wissenschaftlichen Simulations-Workflows:<\/p>\n<ul>\n<li><a href=\"https:\/\/matforge.org\/documentation-best-practices-scientific-python-packages\/\">Best Practices f\u00fcr wissenschaftliche Python-Pakete<\/a> \u2014 Python-spezifische Tooling und Dokumentation Struktur<\/li>\n<li><a href=\"https:\/\/matforge.org\/continuous-integration-research-software-automated-testing-validation\/\"> Kontinuierliche Integration f\u00fcr Forschungssoftware <\/a> - CI \/ CD f\u00fcr automatisiertes Testen und Validieren.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reading-and-understanding-fipy-documentation\/\">Fipy-Dokumentation lesen und verstehen <\/a> - Praktische FIPY-Dokumentationsmuster.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reproducible-research-workflows-docker-and-conda-for-simulation-projects\/\">Reproduzierbare Forschungsworkflows: Docker und Conda <\/a> - Reproduzierbarkeit der Umgebung.<\/li>\n<li><a href=\"https:\/\/matforge.org\/best-practices-for-maintaining-scientific-code\/\"> Best Practices f\u00fcr die Aufrechterhaltung des wissenschaftlichen Codes <\/a> - Langfristige Projektpflege.<\/li>\n<\/ul>\n<h2>Zusammenfassung und n\u00e4chste Schritte<\/h2>\n<p>Die Dokumentation verwandelt Code aus einem fragilen experimentellen Artefakt in ein dauerhaftes Forschungsgut. Das Di\u00e1taxis-Framework gibt Struktur. Die zehn einfachen Regeln geben eine praktische Checkliste. Vorlagen und Tools bieten einen schnellen Ausgangspunkt.<\/p>\n<p>Beginnen Sie mit einem kleinen Schritt: Erstellen Sie eine <code>CITATION.cff<\/code>-Datei und f\u00fcgen Sie eine Anleitung hinzu. Dies erleichtert das Zitieren und Guthaben der Software.<\/p>\n<p>F\u00fcgen Sie dann eine Readme mit Installations-, Schnellstart-, Lizenz- und Dokumentationslinks hinzu. Dies ist das wirkungsvollste Dokument f\u00fcr die Benutzerfreundlichkeit.<\/p>\n<p>Als n\u00e4chstes dokumentieren Sie die API mit konsistenten DocStrings und richten Sie Sphinx oder Mkdocs ein. Dies hilft Benutzern und zuk\u00fcnftigen Betreuern zu verstehen, wie der Code funktioniert.<\/p>\n<p>Schreiben Sie abschlie\u00dfend mindestens eine Anleitung f\u00fcr den h\u00e4ufigsten Anwendungsfall. Das ist oft die Seitenmitarbeiter.<\/p>\n<p>Jede Dokumentation bringt Ihre Software der reproduzierbaren Forschung einen Schritt n\u00e4her.<\/p>\n<h2>Referenzen und Weiterlesen<\/h2>\n<ul>\n<li>Lee, B. D. (2018). Zehn einfache Regeln f\u00fcr die Dokumentation wissenschaftlicher Software. <em> PLoS Computational Biology <\/em>, 14 (12): e1006561. <a href=\"https:\/\/doi.org\/10.1371\/journal.pcbi.1006561\"> doi: 10.1371\/journal.pcbi.1006561 <\/a><\/li>\n<li>Software-Nachhaltigkeitsinstitut. Was sind Best Practices f\u00fcr die Dokumentation der Forschungssoftware? <a href=\"https:\/\/www.software.ac.uk\/blog\/what-are-best-practices-research-software-documentation\"> Quelle <\/a><\/li>\n<li>Procida, D. Di\u00e1taxis: Ein systematischer Ansatz zur Erstellung technischer Dokumentation. <a href=\"https:\/\/diataxis.fr\/\"> Quelle <\/a><\/li>\n<li>Wilson, G. et al. (2014). Best Practices f\u00fcr das wissenschaftliche Rechnen. <em> PLoS Biology <\/em>, 12 (1): e1001745. <a href=\"https:\/\/doi.org\/10.1371\/journal.pbio.1001745\"> doi: 10.1371\/journal.pbio.1001745 <\/a><\/li>\n<li>Journal of Open Source Software. <a href=\"https:\/\/joss.theoj.org\/\"> Quelle <\/a><\/li>\n<li>Lesen Sie die Dokumente. <a href=\"https:\/\/readthedocs.org\/\"> Quelle <\/a><\/li>\n<\/ul>\n<h2>Ben\u00f6tigen Sie Hilfe bei der Strukturierungsdokumentation f\u00fcr Ihr Simulationsprojekt?<\/h2>\n<p>Wenn Ihr Forschungsteam beim Aufbau automatisierter Dokumentations-Pipelines, beim Entwerfen einer di\u00e1taxis-konformen Dokumentationsstruktur oder beim Integrieren der Dokumentation in CI\/CD-Workflows Hilfe ben\u00f6tigt, k\u00f6nnen unsere Experten f\u00fcr Computational Science helfen.<\/p>\n<p>Kontaktieren Sie uns \u00fcber unser <a href=\"https:\/\/matforge.org\/category\/issue-tracking-tickets-technical-requests\/\">Issue Tracking System<\/a>, um die Dokumentationsanforderungen Ihres Projekts zu besprechen.<\/p>\n"},"excerpt":{"rendered":"<p><span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 7<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span>Erfahren Sie, wie Sie Forschungssoftware mit praktischen Vorlagen, dem Di\u00e1taxis-Framework und bew\u00e4hrten Strategien aus dem Software Sustainability Institute und den PLOS-Richtlinien dokumentieren.<\/p>\n","protected":false,"raw":"Erfahren Sie, wie Sie Forschungssoftware mit praktischen Vorlagen, dem Di\u00e1taxis-Framework und bew\u00e4hrten Strategien aus dem Software Sustainability Institute und den PLOS-Richtlinien dokumentieren."},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_locale":"de_DE","_original_post":"https:\/\/matforge.org\/?p=342","iawp_total_views":0,"footnotes":""},"categories":[3],"tags":[],"class_list":["post-882","post","type-post","status-publish","format-standard","hentry","category-issue-tracking-tickets-technical-requests","de-DE"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v28.1 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Dokumentationshandbuch<\/title>\n<meta name=\"description\" content=\"Erfahren Sie, wie Sie Forschungssoftware mit Di\u00e1taxis, Readme-Vorlagen, citation.cff, Sphinx, Mkdocs dokumentieren, die Dokumente lesen und praktische Regeln lesen.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/\" \/>\n<meta property=\"og:locale\" content=\"de_DE\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Dokumentationshandbuch\" \/>\n<meta property=\"og:description\" content=\"Erfahren Sie, wie Sie Forschungssoftware mit Di\u00e1taxis, Readme-Vorlagen, citation.cff, Sphinx, Mkdocs dokumentieren, die Dokumente lesen und praktische Regeln lesen.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/\" \/>\n<meta property=\"og:site_name\" content=\"matforge.org\" \/>\n<meta property=\"article:published_time\" content=\"2026-07-30T12:23:24+00:00\" \/>\n<meta name=\"author\" content=\"Priya Nair\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Verfasst von\" \/>\n\t<meta name=\"twitter:data1\" content=\"Priya Nair\" \/>\n\t<meta name=\"twitter:label2\" content=\"Gesch\u00e4tzte Lesezeit\" \/>\n\t<meta name=\"twitter:data2\" content=\"11\u00a0Minuten\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/\"},\"author\":{\"name\":\"Priya Nair\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\"},\"headline\":\"Forschungssoftware-Dokumentation: Ein praktischer Leitfaden f\u00fcr Wissenschaftler\",\"datePublished\":\"2026-07-30T12:23:24+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/\"},\"wordCount\":1970,\"commentCount\":0,\"articleSection\":[\"Issue Tracking, Tickets & amp; Technische Anfragen\"],\"inLanguage\":\"de\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/\",\"url\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/\",\"name\":\"Dokumentationshandbuch\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\"},\"datePublished\":\"2026-07-30T12:23:24+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\"},\"description\":\"Erfahren Sie, wie Sie Forschungssoftware mit Di\u00e1taxis, Readme-Vorlagen, citation.cff, Sphinx, Mkdocs dokumentieren, die Dokumente lesen und praktische Regeln lesen.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/#breadcrumb\"},\"inLanguage\":\"de\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/research-software-documentation-practical-guide-scientists\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/matforge.org\\\/de\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Forschungssoftware-Dokumentation: Ein praktischer Leitfaden f\u00fcr Wissenschaftler\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\",\"url\":\"https:\\\/\\\/matforge.org\\\/\",\"name\":\"matforge.org\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/matforge.org\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"de\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\",\"name\":\"Priya Nair\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"de\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"caption\":\"Priya Nair\"},\"sameAs\":[\"http:\\\/\\\/matforge.org\"],\"url\":\"https:\\\/\\\/matforge.org\\\/author\\\/priya-nair\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Dokumentationshandbuch","description":"Erfahren Sie, wie Sie Forschungssoftware mit Di\u00e1taxis, Readme-Vorlagen, citation.cff, Sphinx, Mkdocs dokumentieren, die Dokumente lesen und praktische Regeln lesen.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/","og_locale":"de_DE","og_type":"article","og_title":"Dokumentationshandbuch","og_description":"Erfahren Sie, wie Sie Forschungssoftware mit Di\u00e1taxis, Readme-Vorlagen, citation.cff, Sphinx, Mkdocs dokumentieren, die Dokumente lesen und praktische Regeln lesen.","og_url":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/","og_site_name":"matforge.org","article_published_time":"2026-07-30T12:23:24+00:00","author":"Priya Nair","twitter_card":"summary_large_image","twitter_misc":{"Verfasst von":"Priya Nair","Gesch\u00e4tzte Lesezeit":"11\u00a0Minuten"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/#article","isPartOf":{"@id":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/"},"author":{"name":"Priya Nair","@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795"},"headline":"Forschungssoftware-Dokumentation: Ein praktischer Leitfaden f\u00fcr Wissenschaftler","datePublished":"2026-07-30T12:23:24+00:00","mainEntityOfPage":{"@id":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/"},"wordCount":1970,"commentCount":0,"articleSection":["Issue Tracking, Tickets & amp; Technische Anfragen"],"inLanguage":"de","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/","url":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/","name":"Dokumentationshandbuch","isPartOf":{"@id":"https:\/\/matforge.org\/#website"},"datePublished":"2026-07-30T12:23:24+00:00","author":{"@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795"},"description":"Erfahren Sie, wie Sie Forschungssoftware mit Di\u00e1taxis, Readme-Vorlagen, citation.cff, Sphinx, Mkdocs dokumentieren, die Dokumente lesen und praktische Regeln lesen.","breadcrumb":{"@id":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/#breadcrumb"},"inLanguage":"de","potentialAction":[{"@type":"ReadAction","target":["https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/matforge.org\/de\/research-software-documentation-practical-guide-scientists\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/matforge.org\/de\/"},{"@type":"ListItem","position":2,"name":"Forschungssoftware-Dokumentation: Ein praktischer Leitfaden f\u00fcr Wissenschaftler"}]},{"@type":"WebSite","@id":"https:\/\/matforge.org\/#website","url":"https:\/\/matforge.org\/","name":"matforge.org","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/matforge.org\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"de"},{"@type":"Person","@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795","name":"Priya Nair","image":{"@type":"ImageObject","inLanguage":"de","@id":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","caption":"Priya Nair"},"sameAs":["http:\/\/matforge.org"],"url":"https:\/\/matforge.org\/author\/priya-nair\/"}]}},"_links":{"self":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/882","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/comments?post=882"}],"version-history":[{"count":1,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/882\/revisions"}],"predecessor-version":[{"id":1026,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/882\/revisions\/1026"}],"wp:attachment":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/media?parent=882"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/categories?post=882"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/tags?post=882"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}