mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-07 17:44:01 +00:00
restructured parts, shortened, linked more software.
This commit is contained in:
Nicole Dresselhaus
parent
6202af618a
commit
dac7b3f039
@ -2165,10 +2165,10 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
">
|
||||
<meta name="citation_author" content="Nicole Dresselhaus">
|
||||
<meta name="citation_author" content="GPT-4.5 &amp;quot;deep research"">
|
||||
<meta name="citation_publication_date" content="2025-05-08">
|
||||
<meta name="citation_cover_date" content="2025-05-08">
|
||||
<meta name="citation_publication_date" content="2025-06-05">
|
||||
<meta name="citation_cover_date" content="2025-06-05">
|
||||
<meta name="citation_year" content="2025">
|
||||
<meta name="citation_online_date" content="2025-05-08">
|
||||
<meta name="citation_online_date" content="2025-06-05">
|
||||
<meta name="citation_language" content="de">
|
||||
<meta name="citation_reference" content="citation_title=Collaborative Historical Research in the Age of Big Data: Lessons from an Interdisciplinary Project;,citation_abstract=This book is output of the Living with Machines project;,citation_author=Ruth Ahnert;,citation_author=Emma Griffin;,citation_author=Mia Ridge;,citation_author=Giorgia Tolfo;,citation_publication_date=2023;,citation_cover_date=2023;,citation_year=2023;,citation_fulltext_html_url=https://www.cambridge.org/core/elements/collaborative-historical-research-in-the-age-of-big-data/839C422CCAA6C1699DE8D353B3A1960D;,citation_doi=10.1017/9781009175548;,citation_language=en-US;,citation_series_title=Cambridge Elements: Historical Theory and Practice;">
|
||||
<meta name="citation_reference" content="citation_title=DFG-Praxisregeln &amp;amp;quot;Digitalisierung&quot;. Aktualisierte Fassung 2022.;,citation_abstract=Die DFG-Praxisregeln „Digitalisierung“ stellen eine zentrale Grundlage für DFG-geförderte Projekte im Programm „Digitalisierung und Erschließung“ dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschließung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zugänglichkeit und Anschlussfähigkeit geförderter Projekte und der in diesem Zusammenhang entstehenden Infrastruktur. Das vorliegende Dokument stellt eine aktualisierte Fassung der zuletzt 2016 durch die DFG publizierten Praxisregeln dar. Es wurde in Absprache mit der DFG-Geschäftsstelle durch eine vom NFDI-Konsortium NFDI4Culture initiierte Autor*innengruppe erarbeitet, deren Mitglieder mehrheitlich seit langem an der Ausgestaltung der Praxisregeln beteiligt waren sowie aktiv in die NFDI-Konsortien NFDI4Culture, NFDI4Memory, NFDI4Objects und Text+ eingebunden sind. Die jetzt überarbeitet vorliegenden Praxisregeln „Digitalisierung“ dienen als Ausgangspunkt für eine material- und communitybezogene Ausdifferenzierung der Praxisregeln durch die Communitys. Alle mit der Digitalisierung forschungsrelevanter Objekte befassten Communitys und Einrichtungen sind dazu aufgerufen, mit ihrer Expertise am weiteren Prozess mitzuwirken.;,citation_author=Reinhard Altenhöner;,citation_author=Andreas Berger;,citation_author=Christian Bracht;,citation_author=Paul Klimpel;,citation_author=Sebastian Meyer;,citation_author=Andreas Neuburger;,citation_author=Thomas Stäcker;,citation_author=Regine Stein;,citation_publication_date=2023-02-16;,citation_cover_date=2023-02-16;,citation_year=2023;,citation_fulltext_html_url=https://zenodo.org/record/7435724;,citation_language=deu;">
|
||||
@ -2267,6 +2267,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
<ul class="collapse">
|
||||
<li><a href="#checkliste-für-die-mindest-dokumentation" id="toc-checkliste-für-die-mindest-dokumentation" class="nav-link" data-scroll-target="#checkliste-für-die-mindest-dokumentation">Checkliste für die Mindest-Dokumentation</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#implementierung-aller-vorschläge-als-ready-to-use-repository" id="toc-implementierung-aller-vorschläge-als-ready-to-use-repository" class="nav-link" data-scroll-target="#implementierung-aller-vorschläge-als-ready-to-use-repository">Implementierung aller Vorschläge als ready-to-use Repository</a></li>
|
||||
<li><a href="#fazit" id="toc-fazit" class="nav-link" data-scroll-target="#fazit">Fazit</a></li>
|
||||
|
||||
|
||||
@ -2322,7 +2323,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
<div>
|
||||
<div class="quarto-title-meta-heading">Veröffentlichungsdatum</div>
|
||||
<div class="quarto-title-meta-contents">
|
||||
<p class="date">8. Mai 2025</p>
|
||||
<p class="date">5. Juni 2025</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@ -2349,7 +2350,7 @@ Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
</section>
|
||||
<section id="inhaltliche-anforderungen-an-die-dokumentation" class="level2 page-columns page-full">
|
||||
<h2 class="anchored" data-anchor-id="inhaltliche-anforderungen-an-die-dokumentation">Inhaltliche Anforderungen an die Dokumentation</h2>
|
||||
<p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong>. Insbesondere sind folgende Inhalte essenziell:</p>
|
||||
<p>Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft das fehlende <em>Big Picture</em>, also eine klare Darstellung des <em>Was</em> und <em>Warum</em>. Die Dokumentation sollte daher alle <strong>Informationen abdecken, die zum Verstehen, Nutzen und Weiterentwickeln der Software nötig sind</strong><span class="citation" data-cites="lamprecht2020towards">[<a href="#ref-lamprecht2020towards" role="doc-biblioref">4</a>]</span>. Insbesondere sind folgende Inhalte essenziell:</p>
|
||||
<section id="ziel-und-zweck-der-software-statement-of-need" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="ziel-und-zweck-der-software-statement-of-need">Ziel und Zweck der Software (Statement of Need)</h3>
|
||||
<p>Beschreiben Sie <em>was die Software tut</em> und <em>warum sie entwickelt wurde</em>. Nennen Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung, die mit der Software adressiert wird, sowie die <em>Zielgruppe</em> (wer soll sie nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen. Beispiel: <em>“Dieses Tool extrahiert Personen-Netzwerke aus historischen Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”</em> Eine klare Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die eigene Herangehensweise einordnen (z. B. was die Software anders oder besser macht).</p>
|
||||
@ -2377,14 +2378,31 @@ Prinzip
|
||||
<div class="callout-body-container callout-body">
|
||||
<p>Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.</p>
|
||||
</div>
|
||||
</div></div><ul>
|
||||
<li><strong>Typische Nutzungsszenarien und Workflows:</strong> Zeigen Sie anhand von <em>Beispielen</em>, wie die Software benutzt wird. Ein <strong>Quickstart-Beispiel</strong> senkt die Einstiegshürde enorm. Dies kann z. B. eine Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum gewünschten Ergebnis kommt (<em>“Getting Started”</em>-Abschnitt). Beschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf. können mehrere Anwendungsfälle skizziert werden (z. B. <em>“Analyse eines einzelnen Briefes”</em> vs. <em>“Batch-Verarbeitung eines gesamten Korpus”</em>). Diese Beispiele sollten realistisch und möglichst <em>repräsentativ für wissenschaftliche Anwendungen</em> sein. Nutzen Sie gerne kleine Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei Kommandozeilentools, via <code>--help</code> dokumentiert).</li>
|
||||
</ul>
|
||||
</div></div><div class="callout callout-style-default callout-note callout-titled" title="Typische Nutzungsszenarien und Workflows">
|
||||
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-2-contents" aria-controls="callout-2" aria-expanded="false" aria-label="Toggle callout">
|
||||
<div class="callout-icon-container">
|
||||
<i class="callout-icon"></i>
|
||||
</div>
|
||||
<div class="callout-title-container flex-fill">
|
||||
Typische Nutzungsszenarien und Workflows
|
||||
</div>
|
||||
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
|
||||
</div>
|
||||
<div id="callout-2" class="callout-2-contents callout-collapse collapse">
|
||||
<div class="callout-body-container callout-body">
|
||||
<p>Zeigen Sie anhand von <em>Beispielen</em>, wie die Software benutzt wird. Ein <strong>Quickstart-Beispiel</strong> senkt die Einstiegshürde enorm. Dies kann z. B. eine Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum gewünschten Ergebnis kommt (<em>“Getting Started”</em>-Abschnitt).</p>
|
||||
<p>Beschreiben Sie typische Workflows in nachvollziehbaren Schritten: Eingabe vorbereiten, Software-Befehl/GUI-Aktion ausführen, Ausgabe interpretieren. Ggf. können mehrere Anwendungsfälle skizziert werden (z. B. <em>“Analyse eines einzelnen Briefes”</em> vs. <em>“Batch-Verarbeitung eines gesamten Korpus”</em>).</p>
|
||||
<p>Diese Beispiele sollten realistisch und möglichst <em>repräsentativ für wissenschaftliche Anwendungen</em> sein. Nutzen Sie gerne kleine Datensamples oder Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können. Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von Ausschnitten oder, bei Kommandozeilentools, via <code>--help</code> dokumentiert).</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="wissenschaftlicher-hintergrund-und-theoretischer-kontext" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="wissenschaftlicher-hintergrund-und-theoretischer-kontext">Wissenschaftlicher Hintergrund und theoretischer Kontext</h3>
|
||||
<p>Da es sich um Forschungssoftware handelt, sollten Sie den <em>wissenschaftlichen Kontext</em> <a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform. Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”</em> Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst. Wichtig ist, dass die Dokumentation den <strong>Brückenschlag zwischen Code und Forschung</strong> herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.</p>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div></section>
|
||||
<p>Da es sich um Forschungssoftware handelt, sollten Sie den <em>wissenschaftlichen Kontext</em> <a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> offenlegen. Das heißt, erklären Sie die grundlegenden Methoden, Algorithmen oder Modelle, die in der Software umgesetzt sind, zumindest in Überblicksform.</p>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Dieser Hintergrundteil unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller Dokumentation: Es geht nicht nur um <em>wie</em> man das Tool benutzt, sondern auch <em>warum</em> es so funktioniert (Stichwort Nachvollziehbarkeit).</p></div></div><p>Verweisen Sie auf <em>relevante Publikationen</em> oder Theorien, damit andere die wissenschaftliche Grundlage nachvollziehen können. Beispielsweise: <em>“Die Implementierung folgt dem Algorithmus von Müller et al. (2019) zur Netzwerkanalyse historischer Korrespondenz.”</em> Halten Sie diesen Abschnitt aber prägnant – Details gehören in die Forschungsarbeit selbst.</p>
|
||||
<p>Wichtig ist, dass die Dokumentation den <strong>Brückenschlag zwischen Code und Forschung</strong> herstellt. Da viele Wissenschaftler*innen zentrale Aspekte lieber in ihren Artikeln dokumentieren, sollte in der Software-Dokumentation zumindest eine Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer*innen, unter welchen Annahmen oder Theorien das Tool funktioniert.</p>
|
||||
</section>
|
||||
<section id="bekannte-limitationen-annahmen-und-fehlermeldungen" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="bekannte-limitationen-annahmen-und-fehlermeldungen">Bekannte Limitationen, Annahmen und Fehlermeldungen</h3>
|
||||
<p>Geben Sie ehrlich Auskunft über die <em>Grenzen der Software</em>:</p>
|
||||
@ -2399,12 +2417,12 @@ Prinzip
|
||||
<section id="weiterentwicklung-und-beitragsmöglichkeiten" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="weiterentwicklung-und-beitragsmöglichkeiten">Weiterentwicklung und Beitragsmöglichkeiten</h3>
|
||||
<p>Obwohl viele Digital-Humanities-Tools primär von Einzelpersonen genutzt werden, sollte dennoch angegeben werden, wie andere ggf. <em>zur Software beitragen oder Support erhalten</em> können. Ein kurzer Hinweis auf den Issue-Tracker (z. B. <em>“Fehler bitte über GitHub-Issues melden”</em>) oder auf die Kontaktmöglichkeit zum*zur Autor*in (E-Mail) gehört dazu.</p>
|
||||
<p>Ebenso können <strong>Community Guidelines</strong> skizziert werden: etwa Codierstandards oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte reicht oft ein Satz wie <em>“Beiträge durch Pull Requests sind willkommen; bei Fragen wenden Sie sich an…”</em>. <a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a></p>
|
||||
<p>Ebenso können <strong>Community Guidelines</strong> skizziert werden: etwa Code-Standards oder ein Verhaltenskodex, falls Beiträge erwartet werden. Für kleinere Projekte reicht oft ein Satz wie <em>“Beiträge durch Pull Requests sind willkommen; bei Fragen wenden Sie sich an…”</em>. <a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a></p>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn2"><p><sup>2</sup> 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.</p></div></div></section>
|
||||
<section id="projekt-metadaten-lizenz-zitation-version" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="projekt-metadaten-lizenz-zitation-version">Projekt-Metadaten (Lizenz, Zitation, Version)</h3>
|
||||
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten. <strong>Lizenzinformationen</strong> klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine <strong>LICENSE-Datei</strong> 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.</p>
|
||||
<p>Zudem sollte angegeben werden, wie die Software <strong>zitiert</strong> werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt <em>“Zitation”</em> oder eine <strong>CITATION-Datei</strong> 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 <span class="citation" data-cites="NoyEtAl2019IndustryscaleKnowledge">[<a href="#ref-NoyEtAl2019IndustryscaleKnowledge" role="doc-biblioref">4</a>]</span>.</p>
|
||||
<p>Teil der Dokumentation sind auch formale Informationen, die im Repository leicht zugänglich sein sollten<span class="citation" data-cites="lamprecht2020towards">[<a href="#ref-lamprecht2020towards" role="doc-biblioref">4</a>]</span>. <strong>Lizenzinformationen</strong> klären die rechtlichen Bedingungen der Nutzung und Weiterverbreitung. Es ist Best Practice, eine <strong>LICENSE-Datei</strong> 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.</p>
|
||||
<p>Zudem sollte angegeben werden, wie die Software <strong>zitiert</strong> werden kann (z. B. DOI, Paper-Referenz). Ein eigener Abschnitt <em>“Zitation”</em> oder eine <strong>CITATION-Datei</strong> 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 <span class="citation" data-cites="NoyEtAl2019IndustryscaleKnowledge">[<a href="#ref-NoyEtAl2019IndustryscaleKnowledge" role="doc-biblioref">5</a>]</span>.</p>
|
||||
<p>Schließlich ist es sinnvoll, eine <strong>Versionsnummer</strong> 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<span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span>.</p>
|
||||
</section>
|
||||
<section id="zusammenfassung-der-inhaltlichen-anforderungen" class="level3">
|
||||
@ -2520,11 +2538,13 @@ Prinzip
|
||||
<li>klar strukturiert und in einem einfach handhabbaren Format vorliegen</li>
|
||||
<li>ohne spezielle Umgebung lesbar sein</li>
|
||||
</ul>
|
||||
<p>Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern, Software (und deren Doku) <em>auffindbar</em> und <em>zugänglich</em> zu machen, ohne Hürden. Eine <strong>gut gepflegte</strong> README in <a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a> erfüllt diese Anforderungen in den meisten Fällen optimal.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="die-dokumentation-selbst" class="level2 page-columns page-full">
|
||||
<h2 class="anchored" data-anchor-id="die-dokumentation-selbst">Die Dokumentation selbst</h2>
|
||||
<p>Gerade weil Forschende wenig Zeit haben, muss die Dokumentation <strong>effizient</strong> gestaltet sein. Für typische Forschungssoftware-Projekte in den Geisteswissenschaften wird ein Umfang von <em>maximal ca. 10 Seiten</em> (bei Bedarf verteilt auf mehrere Dateien) als ausreichend erachtet.</p>
|
||||
<section id="umfang-und-fokus-der-dokumentation" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="umfang-und-fokus-der-dokumentation">Umfang und Fokus der Dokumentation</h3>
|
||||
|
||||
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-tip callout-titled" title="Prinzip">
|
||||
<div class="callout-header d-flex align-content-center">
|
||||
@ -2537,11 +2557,12 @@ Prinzip
|
||||
</div>
|
||||
<div class="callout-body-container callout-body">
|
||||
<p>Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?</p>
|
||||
<ul>
|
||||
<li>Wenn ja, ist der Detailgrad angemessen</li>
|
||||
<li>Wenn die Person hingegen nach 10 Seiten oder mehr als 1 Stunde immer noch nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div></div><p>Gerade weil Forschende wenig Zeit haben, muss die Dokumentation <strong>effizient</strong> gestaltet sein – sie soll alle wichtigen Informationen enthalten, aber auch nicht unnötig ausschweifen. Für typische Forschungssoftware-Projekte in den Geisteswissenschaften wird ein Umfang von <em>maximal ca. 10 Seiten</em> (bei Bedarf verteilt auf mehrere Dateien) als ausreichend erachtet. Dieser Richtwert verhindert, dass die Doku zu einer unüberschaubaren Abhandlung wird, und zwingt zur Fokussierung auf das Wesentliche. Wichtig ist der <strong>Inhalt, nicht die Länge</strong>: eine kürzere, aber inhaltsreiche Dokumentation ist besser als eine lange, die nichts aussagt.</p>
|
||||
<section id="umfang-und-fokus-der-dokumentation" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="umfang-und-fokus-der-dokumentation">Umfang und Fokus der Dokumentation</h3>
|
||||
<p>Ein effizienter Umfang lässt sich erreichen, indem sie <strong>alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles andere skippen</strong>.</p>
|
||||
</div></div><p>Ein effizienter Umfang lässt sich erreichen, indem sie <strong>alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles andere skippen</strong>.</p>
|
||||
<div class="bad-practice">
|
||||
<p>Negativbeispiele umfassen:</p>
|
||||
<ul>
|
||||
@ -2557,26 +2578,7 @@ Prinzip
|
||||
<li>und einfache Sätze</li>
|
||||
</ul>
|
||||
<p>erhöhen die Lesbarkeit.</p>
|
||||
<p>Fachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht kennen.</p>
|
||||
<p>Die Obergrenze von ~10 Seiten ist ein Richtwert. Umfangreiche Projekte könnten etwas mehr benötigen, sehr kleine Tools kommen mit einer Seite aus. Das Ziel ist, dass ein interessierter Nutzer die Dokumentation in überschaubarer Zeit durchsehen kann.</p>
|
||||
<p>Ein guter Test ist: <strong>Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen bringen und ein einfaches Beispiel ausführen?</strong></p>
|
||||
<ul>
|
||||
<li>Wenn ja, ist der Detailgrad angemessen</li>
|
||||
<li>Wenn die Person hingegen nach 10 Seiten oder mehr als 1 Stunde immer noch nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.</li>
|
||||
</ul>
|
||||
<p>Fügen Sie zur Not eine kurze <em>Übersicht/Zusammenfassung</em> am Anfang ein, die das Wichtigste in Kürze nennt – viele Leser entscheiden in wenigen Minuten, ob sie eine Software weiter betrachten oder nicht, und hier zählt der erste Eindruck.</p>
|
||||
</section>
|
||||
<section id="priorisierung-bei-zeitmangel" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="priorisierung-bei-zeitmangel">Priorisierung bei Zeitmangel</h3>
|
||||
<p>Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwickler*innendokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern nötig, um den Hauptnutzerfluss nicht zu überfrachten.</p>
|
||||
<section id="minimaldokumentation-kurze-kommentare" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="minimaldokumentation-kurze-kommentare">Minimaldokumentation: kurze Kommentare</h4>
|
||||
<p>Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (<em>“keine Dokumentation”</em> ist keine Option). <em>Good Enough Practices</em><span class="citation" data-cites="WilsonEtAl2017Goodenoughpractices">[<a href="#ref-WilsonEtAl2017Goodenoughpractices" role="doc-biblioref">3</a>]</span> empfehlen, als ersten Schritt zumindest einen <strong>kurzen erklärenden Kommentar am Anfang jedes Scripts</strong> oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. Später kann die Dokumentation erweitert werden, insbesondere wenn die Software in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B. durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst <em>klein</em> anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte 30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).</p>
|
||||
</section>
|
||||
<section id="verlinkte-dokumentation-ist-auch-dokumentation" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="verlinkte-dokumentation-ist-auch-dokumentation">Verlinkte Dokumentation ist auch Dokumentation</h4>
|
||||
<p>Nutzen Sie <strong>Verweise und vorhandene Ressourcen</strong>. Wenn z. B. Ihr Tool auf einem komplizierten Setup (Datenbank, Webserver) aufbaut, brauchen Sie nicht jede Installationsoption im Detail in Ihrer Doku zu reproduzieren – verlinken Sie auf offizielle Installationsanleitungen dieser Abhängigkeiten, und nennen Sie nur Ihre spezifischen Konfigurationen und verlinken sie auf die Dokumentation des Setup-Elementes für alles weitere. Ebenso können Tutorials oder Papers, die schon existieren, als weiterführende Links angegeben werden, anstatt Inhalte redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.</p>
|
||||
</section>
|
||||
<p><strong>Fachtermini</strong> aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht kennen.</p>
|
||||
<section id="fokus-auf-nutzerinnen---nicht-entwicklerinnen" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="fokus-auf-nutzerinnen---nicht-entwicklerinnen">Fokus auf Nutzer*innen - nicht Entwickler*innen</h4>
|
||||
<p>Stellen Sie sich beim Schreiben der Doku die verschiedenen <em>Nutzerrollen</em> vor: <strong>“Zukünftiges Ich”</strong>, <strong>Kolleg*innen</strong>, <strong>Fachforscher*innen anderer Disziplin</strong> und ggf. <strong>Software-Entwickler*innen, die den Code erweitern</strong>. Jede dieser Gruppen möchte bestimmte Dinge wissen.</p>
|
||||
@ -2593,6 +2595,18 @@ Prinzip
|
||||
</ul>
|
||||
<p>Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für Entwickler*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche Entwickler*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code gut zu kommentieren und eventuell eine grobe Architekturübersicht bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, <strong>das Nutzen und Verstehen der Software von außen</strong> zu ermöglichen.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="priorisierung-bei-zeitmangel" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="priorisierung-bei-zeitmangel">Priorisierung bei Zeitmangel</h3>
|
||||
<p>Dieser Katalog adressiert primär die Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool später wieder anfassen). Entwickler*innendokumentation (z. B. detaillierte API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten werden, sofern nötig, um den Hauptnutzerfluss nicht zu überfrachten.</p>
|
||||
<section id="minimaldokumentation-kurze-kommentare" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="minimaldokumentation-kurze-kommentare">Minimaldokumentation: kurze Kommentare</h4>
|
||||
<p>Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt (<em>“keine Dokumentation”</em> ist keine Option). <em>Good Enough Practices</em><span class="citation" data-cites="WilsonEtAl2017Goodenoughpractices">[<a href="#ref-WilsonEtAl2017Goodenoughpractices" role="doc-biblioref">3</a>]</span> empfehlen, als ersten Schritt zumindest einen <strong>kurzen erklärenden Kommentar am Anfang jedes Scripts</strong> oder eine README mit ein paar Sätzen zu erstellen. Diese Hürde ist niedrig und bringt bereits Nutzen – selbst wenn (noch) keine ausführliche Handbuch-Doku existiert. Später kann die Dokumentation erweitert werden, insbesondere wenn die Software in Kooperation entsteht oder mehr Nutzer gewinnt. Es hat sich gezeigt, dass ausführliche Dokumentation oft erst entsteht, wenn ein echter Bedarf (z. B. durch externe Nutzer) vorhanden ist. Daher: zögern Sie nicht, zunächst <em>klein</em> anzufangen, aber stellen Sie sicher, dass zumindest die kritischen Informationen sofort verfügbar sind (lieber ein 2-seitiges README heute, als das perfekte 30-seitige Handbuch in zwei Jahren, das evtl. nie geschrieben wird).</p>
|
||||
</section>
|
||||
<section id="verlinkte-dokumentation-ist-auch-dokumentation" class="level4">
|
||||
<h4 class="anchored" data-anchor-id="verlinkte-dokumentation-ist-auch-dokumentation">Verlinkte Dokumentation ist auch Dokumentation</h4>
|
||||
<p>Nutzen Sie <strong>Verweise und vorhandene Ressourcen</strong>. Wenn z. B. Ihr Tool auf einem komplizierten Setup (Datenbank, Webserver) aufbaut, brauchen Sie nicht jede Installationsoption im Detail in Ihrer Doku zu reproduzieren – verlinken Sie auf offizielle Installationsanleitungen dieser Abhängigkeiten, und nennen Sie nur Ihre spezifischen Konfigurationen und verlinken sie auf die Dokumentation des Setup-Elementes für alles weitere. Ebenso können Tutorials oder Papers, die schon existieren, als weiterführende Links angegeben werden, anstatt Inhalte redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.</p>
|
||||
</section>
|
||||
<section id="und-anschließend" class="level4 page-columns page-full">
|
||||
<h4 class="anchored" data-anchor-id="und-anschließend">Und anschließend?</h4>
|
||||
<p>Wenn der Zeitmangel vorüber ist<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>, sollte man nach und nach das folgende Kapitel umsetzen.</p>
|
||||
@ -2608,7 +2622,7 @@ Prinzip
|
||||
</section>
|
||||
<section id="prinzipien-fair-und-endings" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="prinzipien-fair-und-endings">Prinzipien: FAIR und ENDINGS</h3>
|
||||
<p>Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des <strong>Research Software Engineering</strong><span class="citation" data-cites="Hasselbring2020OpenSourceResearch">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">5</a>]</span> und den <strong>ENDINGS-Prinzipien</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> steht.</p>
|
||||
<p>Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des <strong>Research Software Engineering</strong><span class="citation" data-cites="Hasselbring2020OpenSourceResearch">[<a href="#ref-Hasselbring2020OpenSourceResearch" role="doc-biblioref">6</a>]</span> und den <strong>ENDINGS-Prinzipien</strong><span class="citation" data-cites="EndingsPrinciples221">[<a href="#ref-EndingsPrinciples221" role="doc-biblioref">1</a>]</span> steht.</p>
|
||||
|
||||
<div class="no-row-height column-margin column-container"><div class="callout callout-style-default callout-note callout-titled" title="ENDINGS-Prinzipien">
|
||||
<div class="callout-header d-flex align-content-center">
|
||||
@ -2632,7 +2646,7 @@ ENDINGS-Prinzipien
|
||||
</section>
|
||||
<section id="kontinuierliche-verbesserung-und-feedback" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="kontinuierliche-verbesserung-und-feedback">Kontinuierliche Verbesserung und Feedback</h3>
|
||||
<p>Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:<span class="citation" data-cites="citation-needed">[<a href="#ref-citation-needed" role="doc-biblioref"><strong>citation-needed?</strong></a>]</span></p>
|
||||
<p>Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess. Best Practice sind daher insbesondere:</p>
|
||||
<ul>
|
||||
<li>früh Feedback von Testnutzer*innen oder Kolleg*innen einzuholen: Lassen Sie jemanden die Anleitung befolgen und hören Sie auf Stolpersteine. Oft zeigen sich Lücken erst im Praxistest (“Ich wusste nicht, was ich nach Schritt X tun soll” etc.).</li>
|
||||
<li>Planen Sie Zeiten ein, die Dokumentation nachzuführen, insbesondere wenn sich die Software ändert. Ein lebendiges Projekt wird vielleicht Release für Release die Dokumentation erweitern (evtl. neue Tutorials, neue Module dokumentieren). Spätestens zum Release-Zeitpunkt sollten diese auffallen und ggf. als Issues adressiert werden.</li>
|
||||
@ -2641,9 +2655,7 @@ ENDINGS-Prinzipien
|
||||
</section>
|
||||
<section id="positiv--und-negativbeispiele-studieren" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="positiv--und-negativbeispiele-studieren">Positiv- und Negativbeispiele studieren</h3>
|
||||
<p>Schlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf Projekte mit exzellenter Doku. In der <em><a href="https://joss.theoj.org/" title="The Journal of Open Source Software">Journal of Open Source Software (JOSS)</a></em> oder <a href="https://openresearchsoftware.metajnl.com/" title="The Journal of Open Research Software features peer reviewed Software Metapapers describing research software with high reuse potential."><em>Journal of Open Research Software (JORS)</em></a> werden oft Softwareartikel veröffentlicht, bei denen die zugehörigen Repositorien vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.</p>
|
||||
<p>Achten Sie darauf, wie diese Projekte ihre README strukturieren, welche Abschnitte vorhanden sind und welche nicht. Viele erfolgreiche Projekte haben z. B. eine ähnliche Reihenfolge: Introduction, Installation, Usage, Contributing, License, Citation – ein Muster, das sich bewährt hat.</p>
|
||||
<p>Ebenso gibt es von Initiativen wie der Software Sustainability Institute Blogposts mit Best Practices und sogar Vorlagen (Templates) für Dokumentation.</p>
|
||||
<p>Schlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf Projekte mit exzellenter Doku. Im <em><a href="https://joss.theoj.org/" title="The Journal of Open Source Software">Journal of Open Source Software (JOSS)</a></em> werden z.B. Softwareartikel veröffentlicht, bei denen die zugehörigen Repositorien aufgrund des <a href="https://joss.readthedocs.io/en/latest/review_checklist.html">Review-Prozesses</a> vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.</p>
|
||||
<p>Nutzen Sie solche Ressourcen; sie ersparen einem das Rad neu zu erfinden. Allerdings: Adaptieren Sie sie auf Ihre Bedürfnisse – nicht jede Vorlage passt 1:1.</p>
|
||||
</section>
|
||||
</section>
|
||||
@ -2652,7 +2664,7 @@ ENDINGS-Prinzipien
|
||||
<p>Die Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge erheblich senken. Gerade Forschende, die alleine programmieren, können von <strong>(teil-)automatisierter Dokumentation</strong> profitieren, um konsistente und aktuelle Unterlagen zu erhalten, ohne alles von Hand schreiben zu müssen. Im Folgenden werden einige Tools und Möglichkeiten vorgestellt – samt Empfehlungen, <em>wann</em> ihr Einsatz sinnvoll oder notwendig ist:</p>
|
||||
<section id="jupyter-notebooks-und-literate-programming" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="jupyter-notebooks-und-literate-programming">Jupyter Notebooks und literate programming</h3>
|
||||
<p>Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind <strong>Jupyter Notebooks</strong> bzw. <strong>R Markdown Notebooks</strong> <span class="citation" data-cites="KluyverEtAl2016JupyterNotebookspublishing">[<a href="#ref-KluyverEtAl2016JupyterNotebookspublishing" role="doc-biblioref">6</a>]</span>. Diese erlauben es, <em>ausführbaren Code mit erklärendem Text und Visualisierungen</em> in einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei leisten:</p>
|
||||
<p>Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind <strong>Jupyter Notebooks</strong> bzw. <strong>R Markdown Notebooks</strong> <span class="citation" data-cites="KluyverEtAl2016JupyterNotebookspublishing">[<a href="#ref-KluyverEtAl2016JupyterNotebookspublishing" role="doc-biblioref">7</a>]</span>. Diese erlauben es, <em>ausführbaren Code mit erklärendem Text und Visualisierungen</em> in einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei leisten:</p>
|
||||
<ol type="1">
|
||||
<li>als <strong>Tutorials/Beispiel-Workflows</strong>, die Nutzer interaktiv nachvollziehen können, und</li>
|
||||
<li>als <strong>Reproduzierbarkeits-Dokumentation</strong> für analytische Prozesse.</li>
|
||||
@ -2715,13 +2727,12 @@ Prinzip
|
||||
</div>
|
||||
</div>
|
||||
<div class="callout-body-container callout-body">
|
||||
<p>Benutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden, ist dieses notwendig.</p>
|
||||
<p>Benutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die Software aber woanders eingebunden, ist dieses notwendig. Generation dieser Dokumentation ist daher der beste Weg.</p>
|
||||
</div>
|
||||
</div><div id="fn5"><p><sup>5</sup> kurz für: “Documentation String”</p></div></div><p>Nutzen Sie die Möglichkeit, Dokumentation <em>direkt im Quellcode</em> unterzubringen, z. B. in Form von <strong>Docstrings<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a></strong> (mehrzeilige Strings in Funktionen/Klassen bei Python, <a href="https://roxygen2.r-lib.org/" title="Generator um aus R Docstrings eine Dokumentation zu generieren">Roxygen</a>-Kommentare in R, <a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a>-Kommentare in Java, etc.).</p>
|
||||
<p>Diese dienen doppelt: Zum einen erleichtern sie es Ihnen und Kollegen, den Code beim Lesen zu verstehen, zum anderen können sie von Tools ausgelesen und zu hübschen API-Dokumentationen verarbeitet werden. Idealerweise dokumentieren Sie <em>jede wichtige <strong>oder</strong> von außen sichtbare Funktion, Klasse oder Modul</em> mit einem kurzen Docstring, der Zweck, Parameter, Rückgaben und ggf. Beispiele enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.</p>
|
||||
<p>Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres Ökosystems (z. B. <a href="https://google.github.io/styleguide/">Google Style Guide</a> für Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen). Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie etwa <strong><a href="https://www.pylint.org/" title="Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.">pylint</a></strong>, können die Verwendung erzwingen.</p>
|
||||
<p>Mit Tools, wie <strong><a href="https://www.sphinx-doc.org" title="Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.">Sphinx</a></strong>, <strong><a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a></strong>, <strong><a href="https://www.doxygen.nl/" title="Generator um aus C/C++ Docstrings eine Dokumentation zu generieren">Doxygen</a></strong>, <strong><a href="https://www.mkdocs.org/" title="Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown">MkDocs</a></strong>,<strong><a href="https://pdoc.dev/" title="Generator um aus Python Docstrings eine Dokumentation zu generieren">pdoc</a></strong> und vielen weiteren, können aus Docstrings automatisiert Webseiten oder PDF-Handbücher generiert werden. Sie lesen z. B. die Python-Docstrings und erzeuge daraus strukturiert eine Dokumentation; Häufig kann über Erweiterungen auch dritte Dokumentation direkt eingebunden und verlinkt werden.</p>
|
||||
<p>Der Einsatz solcher Tools ist besonders dann sinnvoll, wenn Ihre Forschungssoftware über eine <em>Programmierschnittstelle (API)</em> verfügt, die von anderen genutzt werden soll, oder wenn das Projekt größer wird und die interne Struktur komplexer ist. In solchen Fällen kann eine <em>API-Referenz</em> (automatisch aus dem Code erzeugt) eine erhebliche Hilfe sein.</p>
|
||||
</section>
|
||||
<section id="versionskontrolle-und-kontinuierliche-dokumentationspflege" class="level3 page-columns page-full">
|
||||
<h3 class="anchored" data-anchor-id="versionskontrolle-und-kontinuierliche-dokumentationspflege">Versionskontrolle und kontinuierliche Dokumentationspflege</h3>
|
||||
@ -2763,11 +2774,30 @@ Prinzip
|
||||
<p>Diese Checkliste kann vor einem “Release” der Software durchgegangen werden, ähnlich einem Review-Prozess (vgl. <a href="https://joss.readthedocs.io/en/latest/review_checklist.html">JOSS Review-Kriterien</a>, die viele dieser Punkte abdecken). Sie hilft zu entscheiden, was noch dokumentiert werden muss und was eventuell weggelassen werden kann. <strong>Alles, was für die obigen Punkte nicht relevant ist, kann man tendenziell aus der Hauptdokumentation herauslassen.</strong></p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="implementierung-aller-vorschläge-als-ready-to-use-repository" class="level2">
|
||||
<h2 class="anchored" data-anchor-id="implementierung-aller-vorschläge-als-ready-to-use-repository">Implementierung aller Vorschläge als ready-to-use Repository</h2>
|
||||
<div class="callout callout-style-default callout-important callout-titled" title="TODO">
|
||||
<div class="callout-header d-flex align-content-center">
|
||||
<div class="callout-icon-container">
|
||||
<i class="callout-icon"></i>
|
||||
</div>
|
||||
<div class="callout-title-container flex-fill">
|
||||
TODO
|
||||
</div>
|
||||
</div>
|
||||
<div class="callout-body-container callout-body">
|
||||
<ul class="task-list">
|
||||
<li><label><input type="checkbox">Hier noch auf unsere Template-Repos verweisen.</label></li>
|
||||
<li><label><input type="checkbox">Template-Repos selbst ggf. automatisch auf Zenodo mit kleinem Erklärungstext veröffentlichen?</label></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="fazit" class="level2">
|
||||
<h2 class="anchored" data-anchor-id="fazit">Fazit</h2>
|
||||
<p>Die hier präsentierten Anforderungen und Empfehlungen bieten einen <strong>Leitfaden für die Dokumentation von Forschungssoftware</strong> in den Digital Humanities. Sie sind darauf ausgerichtet, mit überschaubarem Aufwand maximale <strong>Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit</strong> zu erreichen.</p>
|
||||
<p>Indem zentrale Inhalte (Ziele, Inputs/Outputs, Hintergrund, etc.) klar dokumentiert, ein nutzerfreundliches Format (README im Repo) gewählt, der Umfang fokussiert gehalten und hilfreiche Tools eingesetzt werden, kann die Dokumentation zur Stärke eines Projekts werden statt einem lästigen Anhängsel.</p>
|
||||
<p>So schließt sich der Kreis zwischen guter <strong>Softwareentwicklung</strong> und guter <strong>Wissenschaft</strong><span class="citation" data-cites="Forschungsgemeinschaft2025LeitlinienzurSicherung">[<a href="#ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" role="doc-biblioref">7</a>, Leitlinie 12]</span>: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch wie die Erfahrung zeigt, zahlen sich diese in Form von <em>Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung</em> der Software aus. Mit diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen – trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: <strong>Gut dokumentierte Forschungscode ist nachhaltige Forschung</strong>.</p>
|
||||
<p>So schließt sich der Kreis zwischen guter <strong>Softwareentwicklung</strong> und guter <strong>Wissenschaft</strong><span class="citation" data-cites="Forschungsgemeinschaft2025LeitlinienzurSicherung">[<a href="#ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" role="doc-biblioref">8</a>, Leitlinie 12]</span>: Dokumentation ist das Bindeglied, das Code und Erkenntnis transparent verbindet. In der Praxis bedeutet dies zwar zusätzliche Arbeitsschritte, doch wie die Erfahrung zeigt, zahlen sich diese in Form von <em>Zeiteinsparung bei Nutzern, höherer Zitierbarkeit und größerer Wirkung</em> der Software aus. Mit diesem Anforderungskatalog sind Forschende gut gerüstet, um ihre Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen – trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: <strong>Gut dokumentierte Forschungscode ist nachhaltige Forschung</strong>.</p>
|
||||
</section>
|
||||
|
||||
|
||||
@ -2775,9 +2805,9 @@ Prinzip
|
||||
|
||||
|
||||
|
||||
<div id="quarto-appendix" class="default page-columns page-full"><section id="tabellarische-übersicht-der-dokumentations-bestandteile" class="level2 appendix page-columns page-full"><h2 class="anchored quarto-appendix-heading">Tabellarische Übersicht der Dokumentations-Bestandteile</h2><div class="quarto-appendix-contents page-columns page-full">
|
||||
<div id="quarto-appendix" class="default page-columns page-full"><section id="tabellarische-übersicht-der-dokumentations-bestandteile" class="level2 appendix column-page"><h2 class="anchored quarto-appendix-heading">Tabellarische Übersicht der Dokumentations-Bestandteile</h2><div class="quarto-appendix-contents">
|
||||
|
||||
<div class="column-page-right">
|
||||
<div class>
|
||||
<table class="caption-top table">
|
||||
<caption><em>Empfohlene Dokumentationselemente, Inhalte und Umfang.</em> Diese Übersicht kann als Vorlage dienen, welche Komponenten ein Dokumentationspaket enthalten sollte. Je nach Projekt können einige Elemente wegfallen oder kombiniert werden – entscheidend ist, dass die Kerninformationen (siehe oben) nicht fehlen.</caption>
|
||||
<colgroup>
|
||||
@ -2863,16 +2893,22 @@ Prinzip
|
||||
</div></section><section id="referenz-software" class="level2 appendix"><h2 class="anchored quarto-appendix-heading">Referenz Software</h2><div class="quarto-appendix-contents">
|
||||
|
||||
<ul>
|
||||
<li><a href="https://docs.python.org/3/library/argparse.html" title="Der Argument-Parser der Python-Standardbibliothek">argparse</a>: Der Argument-Parser der Python-Standardbibliothek</li>
|
||||
<li><a href="https://www.doxygen.nl/" title="Generator um aus C/C++ Docstrings eine Dokumentation zu generieren">Doxygen</a>: Generator um aus C/C++ Docstrings eine Dokumentation zu generieren</li>
|
||||
<li><a href="https://git-scm.com" title="Das de-facto Standard-Versionskontrollsystem">git</a>: Versionskontrollsystem</li>
|
||||
<li><a href="https://graphviz.org/" title="Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg">graphviz</a>: Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf vielen Systemen verfügbar und rendert zu pdf/svg</li>
|
||||
<li><a href="https://www.oracle.com/java/technologies/javase/javadoc.html" title="Generator um aus Java Docstrings eine Dokumentation zu generieren">Javadoc</a>: Generator um aus Java Docstrings eine Dokumentation zu generieren</li>
|
||||
<li><a href="https://en.wikipedia.org/wiki/Markdown" title="Mittlerweile DER Standard bei plaintext-Dokumenten">Markdown</a>: Mittlerweile DER Standard bei plaintext-Dokumenten</li>
|
||||
<li><a href="https://mermaid.js.org/" title="Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden">mermaid.js</a>: Sprache für Diagramme; kann automatisiert (z.b. durch pandoc, javascript im HTML, …) in Bilder gewandelt werden</li>
|
||||
<li><a href="https://www.mkdocs.org/" title="Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown">MkDocs</a>: Sehr einfacher und minimalistischer Generator für statische Websites aus Markdown</li>
|
||||
<li><a href="https://pandoc.org/MANUAL.html#pandocs-markdown" title="DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln und hieraus HTML/PDF u.ä. erstellen">pandoc</a>: DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln und hieraus HTML/PDF u.ä. erstellen</li>
|
||||
<li><a href="https://pdoc.dev/" title="Generator um aus Python Docstrings eine Dokumentation zu generieren">pdoc</a>: Generator um aus Python Docstrings eine Dokumentation zu generieren</li>
|
||||
<li><a href="https://www.pylint.org/" title="Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.">pylint</a>: Linting-Tool für Python. Formatiert Code und weist auf Probleme (z.b. fehlende Dokumentation) hin.</li>
|
||||
<li><a href="https://roxygen2.r-lib.org/" title="Generator um aus R Docstrings eine Dokumentation zu generieren">Roxygen</a>: Generator um aus R Docstrings eine Dokumentation zu generieren</li>
|
||||
<li><a href="https://en.wikipedia.org/wiki/ReStructuredText" title="Alternative zu Markdown.">rst</a>: Alternative zu Markdown.</li>
|
||||
<li><a href="https://www.sphinx-doc.org" title="Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.">Sphinx</a>: Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter readthedocs.com steht.</li>
|
||||
</ul>
|
||||
<hr>
|
||||
</div></section><section id="bibliographie" class="level2 unnumbered appendix"><h2 class="quarto-appendix-heading"></h2><div class="quarto-appendix-contents">
|
||||
</div></section><section id="bibliographie" class="level2 unnumbered appendix column-page"><h2 class="quarto-appendix-heading"></h2><div class="quarto-appendix-contents">
|
||||
|
||||
|
||||
</div></section><section class="quarto-appendix-contents" role="doc-bibliography" id="quarto-bibliography"><h2 class="anchored quarto-appendix-heading">Bibliographie</h2><div id="refs" class="references csl-bib-body" data-entry-spacing="0" role="list">
|
||||
@ -2885,23 +2921,26 @@ Prinzip
|
||||
<div id="ref-WilsonEtAl2017Goodenoughpractices" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">3. </div><div class="csl-right-inline">Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, und Tracy K. Teal. 2017. Good Enough Practices in Scientific Computing. <em>PLOS Computational Biology</em> 13. Public Library of Science: e1005510. <a href="https://doi.org/10.1371/journal.pcbi.1005510">https://doi.org/10.1371/journal.pcbi.1005510</a>.</div>
|
||||
</div>
|
||||
<div id="ref-lamprecht2020towards" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Lamprecht, Anna-Lena, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, u. a. 2020. Towards <span>FAIR</span> Principles for Research Software. <em>Data Science</em> 3. SAGE Publications: 37–59. <a href="https://doi.org/10.3233/DS-190026">https://doi.org/10.3233/DS-190026</a>.</div>
|
||||
</div>
|
||||
<div id="ref-NoyEtAl2019IndustryscaleKnowledge" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. <em>PeerJ Computer Science</em> 2. PeerJ Inc. <a href="https://doi.org/10.7717/peerj-cs.86">https://doi.org/10.7717/peerj-cs.86</a>.</div>
|
||||
<div class="csl-left-margin">5. </div><div class="csl-right-inline">Smith, Arfon M., Daniel S. Katz, und Kyle E. Niemeyer. 2016. Software Citation Principles. <em>PeerJ Computer Science</em> 2. PeerJ Inc. <a href="https://doi.org/10.7717/peerj-cs.86">https://doi.org/10.7717/peerj-cs.86</a>.</div>
|
||||
</div>
|
||||
<div id="ref-Hasselbring2020OpenSourceResearch" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">5. </div><div class="csl-right-inline">Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open <span>Source Research Software</span>. <em>Computer</em> 53: 84–88. <a href="https://doi.org/10.1109/MC.2020.2998235">https://doi.org/10.1109/MC.2020.2998235</a>.</div>
|
||||
<div class="csl-left-margin">6. </div><div class="csl-right-inline">Hasselbring, Wilhelm, Leslie Carr, Simon Hettrick, Heather Packer, und Thanassis Tiropanis. 2020. Open <span>Source Research Software</span>. <em>Computer</em> 53: 84–88. <a href="https://doi.org/10.1109/MC.2020.2998235">https://doi.org/10.1109/MC.2020.2998235</a>.</div>
|
||||
</div>
|
||||
<div id="ref-KluyverEtAl2016JupyterNotebookspublishing" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">6. </div><div class="csl-right-inline">Kluyver, Thomas, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, u. a. 2016. Jupyter <span>Notebooks</span> – a Publishing Format for Reproducible Computational Workflows. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. <a href="https://doi.org/10.3233/978-1-61499-649-1-87">https://doi.org/10.3233/978-1-61499-649-1-87</a>.</div>
|
||||
<div class="csl-left-margin">7. </div><div class="csl-right-inline">Kluyver, Thomas, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, u. a. 2016. Jupyter <span>Notebooks</span> – a Publishing Format for Reproducible Computational Workflows. In, Hrsg. Fernando Loizides und Birgit Scmidt, 87–90. IOS Press. <a href="https://doi.org/10.3233/978-1-61499-649-1-87">https://doi.org/10.3233/978-1-61499-649-1-87</a>.</div>
|
||||
</div>
|
||||
<div id="ref-Forschungsgemeinschaft2025LeitlinienzurSicherung" class="csl-entry" role="listitem">
|
||||
<div class="csl-left-margin">7. </div><div class="csl-right-inline"><em>Leitlinien zur Sicherung guter wissenschaftlicher Praxis</em>. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. <a href="https://doi.org/10.5281/zenodo.14281892">https://doi.org/10.5281/zenodo.14281892</a>.</div>
|
||||
<div class="csl-left-margin">8. </div><div class="csl-right-inline"><em>Leitlinien zur Sicherung guter wissenschaftlicher Praxis</em>. 2024 (Version 1.2). Deutsche Forschungsgemeinschaft. <a href="https://doi.org/10.5281/zenodo.14281892">https://doi.org/10.5281/zenodo.14281892</a>.</div>
|
||||
</div>
|
||||
</div></section><section class="quarto-appendix-contents" id="quarto-citation"><h2 class="anchored quarto-appendix-heading">Zitat</h2><div><div class="quarto-appendix-secondary-label">Mit BibTeX zitieren:</div><pre class="sourceCode code-with-copy quarto-appendix-bibtex"><code class="sourceCode bibtex">@online{dresselhaus2025,
|
||||
author = {Dresselhaus, Nicole and deep research, GPT-4.5},
|
||||
title = {Anforderungskatalog für die Dokumentation von
|
||||
Forschungssoftware (Digital Humanities)},
|
||||
date = {2025-05-08},
|
||||
date = {2025-06-05},
|
||||
langid = {de},
|
||||
abstract = {Diese Dokumentation fasst zusammen, welche
|
||||
wissenschaftlichen Konzepte, Algorithmen und Theorien hinter der
|
||||
@ -2911,7 +2950,7 @@ Prinzip
|
||||
</code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre><div class="quarto-appendix-secondary-label">Bitte zitieren Sie diese Arbeit als:</div><div id="ref-dresselhaus2025" class="csl-entry quarto-appendix-citeas" role="listitem">
|
||||
Dresselhaus, Nicole, and GPT-4.5 deep research. 2025.
|
||||
<span>“Anforderungskatalog für die Dokumentation von Forschungssoftware
|
||||
(Digital Humanities).”</span> May 8, 2025.
|
||||
(Digital Humanities).”</span> June 5, 2025.
|
||||
</div></div></section></div></main>
|
||||
<!-- /main column -->
|
||||
<script id="quarto-html-after-body" type="application/javascript">
|
||||
|
||||
@ -14,7 +14,7 @@ abstract: |
|
||||
Algorithmen und Theorien hinter der Software stehen. Sie dient dazu, den
|
||||
Nutzer*innen zu helfen, die theoretischen Grundlagen nachvollziehbar zu machen.
|
||||
lang: de
|
||||
date: 2025-05-08
|
||||
date: 2025-06-05
|
||||
authors:
|
||||
- name: Nicole Dresselhaus
|
||||
affiliation:
|
||||
@ -94,8 +94,8 @@ diskutiert und Best Practices in Form von Vorlagen und Checklisten vorgestellt.
|
||||
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**. Insbesondere sind
|
||||
folgende Inhalte essenziell:
|
||||
Nutzen und Weiterentwickeln der Software nötig sind**[@lamprecht2020towards,
|
||||
R1]. Insbesondere sind folgende Inhalte essenziell:
|
||||
|
||||
### Ziel und Zweck der Software (Statement of Need)
|
||||
|
||||
@ -150,26 +150,32 @@ _“Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation:
|
||||
bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder
|
||||
große Speicherkapazitäten – sind diese zu nennen.]{.aside}
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.
|
||||
|
||||
:::
|
||||
|
||||
- **Typische Nutzungsszenarien und Workflows:** Zeigen Sie anhand von
|
||||
_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
|
||||
(_“Getting Started”_-Abschnitt). 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”_). Diese Beispiele sollten
|
||||
realistisch und möglichst _repräsentativ für wissenschaftliche Anwendungen_
|
||||
sein. Nutzen Sie gerne kleine Datensamples oder Defaults, damit Nutzer die
|
||||
Beispielschritte direkt ausprobieren können. Idealerweise werden
|
||||
Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in Form von
|
||||
Ausschnitten oder, bei Kommandozeilentools, via `--help` dokumentiert).
|
||||
::: {.callout-note title="Typische Nutzungsszenarien und Workflows"
|
||||
collapse="true"}
|
||||
|
||||
Zeigen Sie anhand von _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 (_“Getting Started”_-Abschnitt).
|
||||
|
||||
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”_).
|
||||
|
||||
Diese Beispiele sollten realistisch und möglichst _repräsentativ für
|
||||
wissenschaftliche Anwendungen_ sein. Nutzen Sie gerne kleine Datensamples oder
|
||||
Defaults, damit Nutzer die Beispielschritte direkt ausprobieren können.
|
||||
Idealerweise werden Code-Beispiele mit ausgegebenen Resultaten gezeigt (z. B. in
|
||||
Form von Ausschnitten oder, bei Kommandozeilentools, via `--help` dokumentiert).
|
||||
|
||||
:::
|
||||
|
||||
### Wissenschaftlicher Hintergrund und theoretischer Kontext
|
||||
|
||||
@ -179,11 +185,14 @@ von rein kommerzieller Dokumentation: Es geht nicht nur um _wie_ man das Tool
|
||||
benutzt, sondern auch _warum_ es so funktioniert (Stichwort
|
||||
Nachvollziehbarkeit).] offenlegen. Das heißt, erklären Sie die grundlegenden
|
||||
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 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.
|
||||
zumindest in Überblicksform.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
@ -220,7 +229,7 @@ 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.
|
||||
|
||||
Ebenso können **Community Guidelines** skizziert werden: etwa Codierstandards
|
||||
Ebenso 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…”_. ^[Dieser Aspekt muss nicht umfangreich sein, zeigt
|
||||
@ -230,12 +239,12 @@ Kontaktaufnahme niedrig ist.]
|
||||
### Projekt-Metadaten (Lizenz, Zitation, Version)
|
||||
|
||||
Teil der Dokumentation sind auch formale Informationen, die im Repository leicht
|
||||
zugänglich sein sollten. **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.
|
||||
zugänglich sein sollten[@lamprecht2020towards]. **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.
|
||||
|
||||
Zudem sollte angegeben werden, wie die Software **zitiert** werden kann (z. B.
|
||||
DOI, Paper-Referenz). Ein eigener Abschnitt _“Zitation”_ oder eine
|
||||
@ -293,7 +302,7 @@ Daten/Code abgelegt werden[@EndingsPrinciples221].
|
||||
|
||||
### Keine proprietären Formate oder Abhängigkeit von Werkzeugen
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Dokumentation gehört zum Code und muss auch ohne Programm lesbar sein.
|
||||
|
||||
@ -363,7 +372,7 @@ leicht auffindbar sind.
|
||||
|
||||
### Übersichtlichkeit und Navigierbarkeit
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
_"Don’t Repeat Yourself"_: Alle Informationen zu einem Thema
|
||||
(Installation/Nutzung/...) an derselben Stelle sammeln und keinesfalls mehrfach
|
||||
@ -409,32 +418,26 @@ Insgesamt gilt: Die Dokumentation sollte
|
||||
- klar strukturiert und in einem einfach handhabbaren Format vorliegen
|
||||
- ohne spezielle Umgebung lesbar sein
|
||||
|
||||
Dieses Prinzip entspricht auch den FAIR- und RSE-Richtlinien, die fordern,
|
||||
Software (und deren Doku) _auffindbar_ und _zugänglich_ zu machen, ohne Hürden.
|
||||
Eine **gut gepflegte** README in [Markdown][] erfüllt diese Anforderungen in den
|
||||
meisten Fällen optimal.
|
||||
|
||||
## Die Dokumentation selbst
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
Gerade weil Forschende wenig Zeit haben, muss die Dokumentation **effizient**
|
||||
gestaltet sein. Für typische Forschungssoftware-Projekte in den
|
||||
Geisteswissenschaften wird ein Umfang von _maximal ca. 10 Seiten_ (bei Bedarf
|
||||
verteilt auf mehrere Dateien) als ausreichend erachtet.
|
||||
|
||||
### Umfang und Fokus der Dokumentation
|
||||
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das Tool zum Laufen
|
||||
bringen und ein einfaches Beispiel ausführen?
|
||||
|
||||
- Wenn ja, ist der Detailgrad angemessen
|
||||
- Wenn die Person hingegen nach 10 Seiten oder mehr als 1 Stunde immer noch
|
||||
nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.
|
||||
|
||||
:::
|
||||
|
||||
Gerade weil Forschende wenig Zeit haben, muss die Dokumentation **effizient**
|
||||
gestaltet sein – sie soll alle wichtigen Informationen enthalten, aber auch
|
||||
nicht unnötig ausschweifen. Für typische Forschungssoftware-Projekte in den
|
||||
Geisteswissenschaften wird ein Umfang von _maximal ca. 10 Seiten_ (bei Bedarf
|
||||
verteilt auf mehrere Dateien) als ausreichend erachtet. Dieser Richtwert
|
||||
verhindert, dass die Doku zu einer unüberschaubaren Abhandlung wird, und zwingt
|
||||
zur Fokussierung auf das Wesentliche. Wichtig ist der **Inhalt, nicht die
|
||||
Länge**: eine kürzere, aber inhaltsreiche Dokumentation ist besser als eine
|
||||
lange, die nichts aussagt.
|
||||
|
||||
### Umfang und Fokus der Dokumentation
|
||||
|
||||
Ein effizienter Umfang lässt sich erreichen, indem sie **alles, was für
|
||||
Nachvollziehbarkeit und Wiederverwendung nötig ist dokumentieren, und alles
|
||||
andere skippen**.
|
||||
@ -460,25 +463,36 @@ Halten Sie auch die Sprache prägnant:
|
||||
|
||||
erhöhen die Lesbarkeit.
|
||||
|
||||
Fachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet
|
||||
**Fachtermini** aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet
|
||||
werden, aber erklären/verlinken Sie sie, falls die Zielnutzer sie evtl. nicht
|
||||
kennen.
|
||||
|
||||
Die Obergrenze von \~10 Seiten ist ein Richtwert. Umfangreiche Projekte könnten
|
||||
etwas mehr benötigen, sehr kleine Tools kommen mit einer Seite aus. Das Ziel
|
||||
ist, dass ein interessierter Nutzer die Dokumentation in überschaubarer Zeit
|
||||
durchsehen kann.
|
||||
#### Fokus auf Nutzer\*innen - nicht Entwickler\*innen
|
||||
|
||||
Ein guter Test ist: **Kann eine neue Person in < 1 Stunde mit Hilfe der Doku das
|
||||
Tool zum Laufen bringen und ein einfaches Beispiel ausführen?**
|
||||
Stellen Sie sich beim Schreiben der Doku die verschiedenen _Nutzerrollen_ vor:
|
||||
**“Zukünftiges Ich”**, **Kolleg\*innen**, **Fachforscher\*innen anderer
|
||||
Disziplin** und ggf. **Software-Entwickler\*innen, die den Code erweitern**.
|
||||
Jede dieser Gruppen möchte bestimmte Dinge wissen.
|
||||
|
||||
- Wenn ja, ist der Detailgrad angemessen
|
||||
- Wenn die Person hingegen nach 10 Seiten oder mehr als 1 Stunde immer noch
|
||||
nicht weiß, wie sie loslegen soll, muss die Doku fokussierter werden.
|
||||
_Forschende_ fragen:
|
||||
|
||||
Fügen Sie zur Not eine kurze _Übersicht/Zusammenfassung_ am Anfang ein, die das
|
||||
Wichtigste in Kürze nennt – viele Leser entscheiden in wenigen Minuten, ob sie
|
||||
eine Software weiter betrachten oder nicht, und hier zählt der erste Eindruck.
|
||||
- Was kann das Tool?
|
||||
- Wie benutze ich es?
|
||||
- In welchem Kontext steht es?
|
||||
|
||||
_Entwicklende Personen_ fragen:
|
||||
|
||||
- Wie kann ich beitragen?
|
||||
- Wie funktioniert es unter der Haube?
|
||||
|
||||
Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf
|
||||
Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für
|
||||
Entwickler\*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später
|
||||
ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche
|
||||
Entwickler\*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code
|
||||
gut zu kommentieren und eventuell eine grobe Architekturübersicht
|
||||
bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, **das Nutzen
|
||||
und Verstehen der Software von außen** zu ermöglichen.
|
||||
|
||||
### Priorisierung bei Zeitmangel
|
||||
|
||||
@ -515,33 +529,6 @@ Setup-Elementes für alles weitere. Ebenso können Tutorials oder Papers, die
|
||||
schon existieren, als weiterführende Links angegeben werden, anstatt Inhalte
|
||||
redundant zu erklären. Das entlastet Ihre Dokumentation und hält sie schlank.
|
||||
|
||||
#### Fokus auf Nutzer\*innen - nicht Entwickler\*innen
|
||||
|
||||
Stellen Sie sich beim Schreiben der Doku die verschiedenen _Nutzerrollen_ vor:
|
||||
**“Zukünftiges Ich”**, **Kolleg\*innen**, **Fachforscher\*innen anderer
|
||||
Disziplin** und ggf. **Software-Entwickler\*innen, die den Code erweitern**.
|
||||
Jede dieser Gruppen möchte bestimmte Dinge wissen.
|
||||
|
||||
_Forschende_ fragen:
|
||||
|
||||
- Was kann das Tool?
|
||||
- Wie benutze ich es?
|
||||
- In welchem Kontext steht es?
|
||||
|
||||
_Entwicklende Personen_ fragen:
|
||||
|
||||
- Wie kann ich beitragen?
|
||||
- Wie funktioniert es unter der Haube?
|
||||
|
||||
Priorisieren Sie zunächst die erstgenannten (Anwender) – deshalb Fokus auf
|
||||
Zweck, Nutzung und Ergebnisse in der Hauptdoku. Detailinfos für
|
||||
Entwickler\*innen (z. B. Code-Struktur, To-do-Liste) können separat oder später
|
||||
ergänzt werden. Für viele kleine Forschungssoftware-Projekte sind ausführliche
|
||||
Entwickler\*innendokumentationen ohnehin nicht nötig – hier reicht es, den Code
|
||||
gut zu kommentieren und eventuell eine grobe Architekturübersicht
|
||||
bereitzustellen. Konzentrieren Sie die Hauptdokumentation darauf, **das Nutzen
|
||||
und Verstehen der Software von außen** zu ermöglichen.
|
||||
|
||||
#### Und anschließend?
|
||||
|
||||
Wenn der Zeitmangel vorüber ist^[als ob DAS je der Fall wäre -.-], sollte man
|
||||
@ -570,7 +557,7 @@ Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
|
||||
**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
|
||||
**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.
|
||||
|
||||
::: {.callout-note title="ENDINGS-Prinzipien" .column-margin}
|
||||
::: {.callout-note .column-margin title="ENDINGS-Prinzipien"}
|
||||
|
||||
Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung
|
||||
von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und
|
||||
@ -593,7 +580,7 @@ Softwarepraxis.
|
||||
### Kontinuierliche Verbesserung und Feedback
|
||||
|
||||
Dokumentation ist kein einmaliges Ereignis, sondern ein fortlaufender Prozess.
|
||||
Best Practice sind daher insbesondere:[@citation-needed]
|
||||
Best Practice sind daher insbesondere:
|
||||
|
||||
- früh Feedback von Testnutzer\*innen oder Kolleg\*innen einzuholen: Lassen Sie
|
||||
jemanden die Anleitung befolgen und hören Sie auf Stolpersteine. Oft zeigen
|
||||
@ -611,19 +598,11 @@ Best Practice sind daher insbesondere:[@citation-needed]
|
||||
### Positiv- und Negativbeispiele studieren
|
||||
|
||||
Schlussendlich ist ein guter Weg, die eigene Dokumentation zu verbessern, ist
|
||||
ein Blick auf Projekte mit exzellenter Doku. In der _[Journal of Open Source
|
||||
Software (JOSS)][JOSS]_ oder [_Journal of Open Research Software (JORS)_][JORS]
|
||||
werden oft Softwareartikel veröffentlicht, bei denen die zugehörigen
|
||||
Repositorien vorbildliche READMEs und Wikis haben. Diese können als Vorlage
|
||||
dienen.
|
||||
|
||||
Achten Sie darauf, wie diese Projekte ihre README strukturieren, welche
|
||||
Abschnitte vorhanden sind und welche nicht. Viele erfolgreiche Projekte haben
|
||||
z. B. eine ähnliche Reihenfolge: Introduction, Installation, Usage,
|
||||
Contributing, License, Citation – ein Muster, das sich bewährt hat.
|
||||
|
||||
Ebenso gibt es von Initiativen wie der Software Sustainability Institute
|
||||
Blogposts mit Best Practices und sogar Vorlagen (Templates) für Dokumentation.
|
||||
ein Blick auf Projekte mit exzellenter Doku. Im _[Journal of Open Source
|
||||
Software (JOSS)][JOSS]_ werden z.B. Softwareartikel veröffentlicht, bei denen
|
||||
die zugehörigen Repositorien aufgrund des
|
||||
[Review-Prozesses](https://joss.readthedocs.io/en/latest/review_checklist.html)
|
||||
vorbildliche READMEs und Wikis haben. Diese können als Vorlage dienen.
|
||||
|
||||
Nutzen Sie solche Ressourcen; sie ersparen einem das Rad neu zu erfinden.
|
||||
Allerdings: Adaptieren Sie sie auf Ihre Bedürfnisse – nicht jede Vorlage passt
|
||||
@ -688,7 +667,7 @@ kann.
|
||||
|
||||
### Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Ab einer Codebasis `> einige tausend Zeilen` oder `>5 nontriviale Module` sollte
|
||||
eine generierte Dokumentation bereitstehen.
|
||||
@ -725,10 +704,11 @@ Sphinx/Doxygen-Doku für die API (s.u.) existiert.
|
||||
|
||||
### Docstrings und API-Dokumentationsgeneratoren
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Benutzt jemand die Software nur, braucht es keine API-Dokumentationen; wird die
|
||||
Software aber woanders eingebunden, ist dieses notwendig.
|
||||
Software aber woanders eingebunden, ist dieses notwendig. Generation dieser
|
||||
Dokumentation ist daher der beste Weg.
|
||||
|
||||
:::
|
||||
|
||||
@ -757,15 +737,9 @@ die Python-Docstrings und erzeuge daraus strukturiert eine Dokumentation; Häufi
|
||||
kann über Erweiterungen auch dritte Dokumentation direkt eingebunden und
|
||||
verlinkt werden.
|
||||
|
||||
Der Einsatz solcher Tools ist besonders dann sinnvoll, wenn Ihre
|
||||
Forschungssoftware über eine _Programmierschnittstelle (API)_ verfügt, die von
|
||||
anderen genutzt werden soll, oder wenn das Projekt größer wird und die interne
|
||||
Struktur komplexer ist. In solchen Fällen kann eine _API-Referenz_ (automatisch
|
||||
aus dem Code erzeugt) eine erhebliche Hilfe sein.
|
||||
|
||||
### Versionskontrolle und kontinuierliche Dokumentationspflege
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Die beste Dokumentation ist die, die sich selbst aktualisiert.
|
||||
|
||||
@ -845,6 +819,16 @@ dokumentiert werden muss und was eventuell weggelassen werden kann. **Alles, was
|
||||
für die obigen Punkte nicht relevant ist, kann man tendenziell aus der
|
||||
Hauptdokumentation herauslassen.**
|
||||
|
||||
## Implementierung aller Vorschläge als ready-to-use Repository
|
||||
|
||||
::: {.callout-important title="TODO"}
|
||||
|
||||
- [ ] Hier noch auf unsere Template-Repos verweisen.
|
||||
- [ ] Template-Repos selbst ggf. automatisch auf Zenodo mit kleinem
|
||||
Erklärungstext veröffentlichen?
|
||||
|
||||
:::
|
||||
|
||||
## Fazit
|
||||
|
||||
Die hier präsentierten Anforderungen und Empfehlungen bieten einen **Leitfaden
|
||||
@ -868,7 +852,7 @@ Softwareprojekte dokumentationstechnisch auf ein solides Fundament zu stellen
|
||||
trotz knapper Zeit und ohne Informatikabschluss. Denn am Ende gilt: **Gut
|
||||
dokumentierte Forschungscode ist nachhaltige Forschung**.
|
||||
|
||||
## Tabellarische Übersicht der Dokumentations-Bestandteile {.appendix}
|
||||
## Tabellarische Übersicht der Dokumentations-Bestandteile {.appendix .column-page}
|
||||
|
||||
::: {.column-page-right}
|
||||
|
||||
@ -917,17 +901,27 @@ Community (kostenfrei; limitierte features) oder Enterprise-Linzenz"
|
||||
|
||||
## Referenz Software {.appendix}
|
||||
|
||||
- [argparse][]: Der Argument-Parser der Python-Standardbibliothek
|
||||
- [Doxygen][]: Generator um aus C/C++ Docstrings eine Dokumentation zu
|
||||
generieren
|
||||
- [git][]: Versionskontrollsystem
|
||||
- [graphviz][]: Textuelle darstellung von Graphen; Standard-Unix-Tool; Auf
|
||||
vielen Systemen verfügbar und rendert zu pdf/svg
|
||||
- [Javadoc][]: Generator um aus Java Docstrings eine Dokumentation zu generieren
|
||||
- [Markdown][]: Mittlerweile DER Standard bei plaintext-Dokumenten
|
||||
- [mermaid.js][]: Sprache für Diagramme; kann automatisiert (z.b. durch pandoc,
|
||||
javascript im HTML, …) in Bilder gewandelt werden
|
||||
- [MkDocs][]: Sehr einfacher und minimalistischer Generator für statische
|
||||
Websites aus Markdown
|
||||
- [pandoc][]: DER Konverter für Dokumente. Kann sehr viel in Markdown wandeln
|
||||
und hieraus HTML/PDF u.ä. erstellen
|
||||
- [pdoc][]: Generator um aus Python Docstrings eine Dokumentation zu generieren
|
||||
- [pylint][]: Linting-Tool für Python. Formatiert Code und weist auf Probleme
|
||||
(z.b. fehlende Dokumentation) hin.
|
||||
- [Roxygen][]: Generator um aus R Docstrings eine Dokumentation zu generieren
|
||||
- [rst][]: Alternative zu Markdown.
|
||||
- [Sphinx][]: Mächtiges Dokumentations-Generierungs-Werkzeug, welches hinter
|
||||
readthedocs.com steht.
|
||||
|
||||
[argparse]:
|
||||
https://docs.python.org/3/library/argparse.html
|
||||
@ -952,9 +946,6 @@ Dokumentation zu generieren"
|
||||
[pdoc]:
|
||||
https://pdoc.dev/
|
||||
"Generator um aus Python Docstrings eine Dokumentation zu generieren"
|
||||
|
||||
---
|
||||
|
||||
[git]: https://git-scm.com "Das de-facto Standard-Versionskontrollsystem"
|
||||
[graphviz]:
|
||||
https://graphviz.org/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user