updates on documentation; regenerated dist
This commit is contained in:
Nicole Dresselhaus
@ -76,15 +76,16 @@ gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware
|
||||
Dieser Anforderungskatalog richtet sich an Forschende, die keine
|
||||
Vollzeit-Programmierer sind, und soll **wissenschaftlich fundierte Richtlinien**
|
||||
für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen
|
||||
berücksichtigen Best Practices des Research Software Engineering (RSE) und damit
|
||||
berücksichtigen Best Practices des Research Software Engineering
|
||||
[RSE](@Hasselbring2020OpenSourceResearch; @Lee2018Tensimplerules) und damit
|
||||
einhergehender Prinzipien wie die des _Endings-Projekts_ für digitale
|
||||
Langlebigkeit [@EndingsPrinciples221] und _FAIR-Prinzipien_ für
|
||||
Software[@BarkerEtAl2022IntroducingFAIR].
|
||||
Langlebigkeit [@EndingsPrinciples221] und
|
||||
_FAIR4RS-Prinzipien_[@BarkerEtAl2022IntroducingFAIR].
|
||||
|
||||
Ziel ist es, ein praxistaugliches Gerüst bereitzustellen, das – trotz
|
||||
Zeitknappheit – die wesentlichen Dokumentationsaspekte abdeckt, um sowohl die
|
||||
**Nachvollziehbarkeit** der Ergebnisse als auch eine **Weiterverwendung** der
|
||||
Software zu ermöglichen[@WilsonEtAl2017Goodenoughpractices].
|
||||
Software zu ermöglichen[@Wilson2017GoodEnoughPractices].
|
||||
|
||||
Im Folgenden werden die Anforderungen an Inhalt, Format und Umfang der
|
||||
Dokumentation definiert, geeignete (teil-)automatisierte Dokumentationswerkzeuge
|
||||
@ -95,8 +96,9 @@ 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**[@EndingsPrinciples221;
|
||||
@Lamprecht2020TowardsFAIRPrinciples, R1]. Insbesondere sind folgende Inhalte
|
||||
essenziell:
|
||||
|
||||
### Ziel und Zweck der Software (Statement of Need)
|
||||
|
||||
@ -151,27 +153,6 @@ _“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}
|
||||
|
||||
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).
|
||||
|
||||
### Wissenschaftlicher Hintergrund und theoretischer Kontext
|
||||
|
||||
Da es sich um Forschungssoftware handelt, sollten Sie den _wissenschaftlichen
|
||||
@ -180,11 +161,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
|
||||
@ -221,7 +205,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
|
||||
@ -231,19 +215,19 @@ 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[@Lamprecht2020TowardsFAIRPrinciples].
|
||||
**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
|
||||
**CITATION-Datei** beschreibt, welche Publikation oder welcher DOI bei
|
||||
Verwendung der Software in wissenschaftlichen Arbeiten anzugeben ist. Dies
|
||||
erhöht die akademische Sichtbarkeit und stellt sicher, dass Autor\*innen Credits
|
||||
für ihre Software bekommen [@NoyEtAl2019IndustryscaleKnowledge].
|
||||
für ihre Software bekommen [@Smith2016SoftwareCitationPrinciples].
|
||||
|
||||
Schließlich ist es sinnvoll, eine **Versionsnummer** der Software zu nennen
|
||||
(idealerweise in README und im Tool selbst), damit Nutzer wissen, auf welche
|
||||
@ -294,7 +278,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.
|
||||
|
||||
@ -360,11 +344,11 @@ Repository (z. B. eine `INSTALL.md` für ausführliche Installationshinweise,
|
||||
- `CITATION.cff` oder `CITATION.md` – wie zu zitieren.
|
||||
|
||||
Diese Dateien sollten konsistent formatiert und wie oben benannt sein, damit sie
|
||||
leicht auffindbar sind.
|
||||
leicht auffindbar und ggf. direkt durch Tools verarbeitbar 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
|
||||
@ -385,6 +369,12 @@ Mantra _"Don’t Repeat Yourself"_ gilt auch für Dokumentation.
|
||||
|
||||
### Beispiele, Codeblöcke und ggf. Abbildungen einbinden
|
||||
|
||||
::: {.callout-tip .column-margin title="Prinzip"}
|
||||
|
||||
Zeigen statt nur beschreiben – konkrete Anwendungsfälle in der Doku verankern.
|
||||
|
||||
:::
|
||||
|
||||
Nutzen Sie die Möglichkeiten von [Markdown][], um die Dokumentation lebendig zu
|
||||
gestalten. Zeigen Sie Code-Beispiele als formatierte Codeblöcke, fügen Sie Links
|
||||
zu weiterführenden Ressourcen ein, oder binden Sie bei Bedarf Abbildungen ein
|
||||
@ -402,40 +392,41 @@ Mehrwert bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im
|
||||
Zweifel hat textuelle Beschreibung Vorrang, um nicht vom **Prinzip “keep it
|
||||
simple”** abzuweichen.
|
||||
|
||||
### Fazit Format und Struktur
|
||||
::: {.callout-note title="Typische Nutzungsszenarien und Workflows"
|
||||
collapse="true"}
|
||||
|
||||
Insgesamt gilt: Die Dokumentation sollte
|
||||
Zeigen Sie anhand von _konkreten Beispielen_, wie die Software benutzt wird. Ein
|
||||
**Quickstart-Beispiel** senkt die Einstiegshürde enorm. Dies kann z. B. eine
|
||||
Anleitung sein, wie man mit wenigen Schritten von einer Eingabedatei zum
|
||||
gewünschten Ergebnis kommt.
|
||||
|
||||
- im gleichen Repository leben wie der Code
|
||||
- klar strukturiert und in einem einfach handhabbaren Format vorliegen
|
||||
- ohne spezielle Umgebung lesbar sein
|
||||
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”_).
|
||||
|
||||
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.
|
||||
Diese Beispiele sollten realistisch und möglichst _repräsentativ für
|
||||
wissenschaftliche Anwendungen_ sein. Nutzen Sie gerne kleine, mitgelieferte
|
||||
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).
|
||||
|
||||
## Die Dokumentation selbst
|
||||
:::
|
||||
|
||||
::: {.callout-tip title="Prinzip" .column-margin}
|
||||
### 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**.
|
||||
@ -461,39 +452,45 @@ 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. Konzentrieren Sie die Hauptdokumentation darauf,
|
||||
**das Nutzen und Verstehen der Software von außen** zu ermöglichen.
|
||||
|
||||
### Priorisierung bei Zeitmangel
|
||||
|
||||
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.
|
||||
Code-Kommentare, technische Architektur) kann separat gehalten werden, oder
|
||||
sogar automatisch erzeugt werden.
|
||||
|
||||
#### Minimaldokumentation: kurze Kommentare
|
||||
|
||||
Beginnen Sie mit einer Minimaldokumentation, die alle Schlüsselaspekte abdeckt
|
||||
(_“keine Dokumentation”_ ist keine Option). _Good Enough
|
||||
Practices_[@WilsonEtAl2017Goodenoughpractices] empfehlen, als ersten Schritt
|
||||
Practices_[@Wilson2017GoodEnoughPractices] empfehlen, als ersten Schritt
|
||||
zumindest einen **kurzen erklärenden Kommentar am Anfang jedes Scripts** 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.
|
||||
@ -516,33 +513,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
|
||||
@ -550,6 +520,40 @@ nach und nach das folgende Kapitel umsetzen.
|
||||
|
||||
## Was macht eine gute Dokumentation aus
|
||||
|
||||
### Formelle Prinzipien: Open-Source-Research, FAIR4RS und ENDINGS
|
||||
|
||||
Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
|
||||
**Research Software Engineering**[@Hasselbring2020OpenSourceResearch] und den
|
||||
**FAIR4RS-[@BarkerEtAl2022IntroducingFAIR]** bzw.
|
||||
**ENDINGS-Prinzipien**[@EndingsPrinciples221] steht.
|
||||
|
||||
::: {.callout-note .column-margin title="FAIR4RS-Prinzipien für Software"}
|
||||
|
||||
Die FAIR4RS-Prinzipien sind eine Anpassung der Ursprünglich nur für Daten
|
||||
gedachten FAIR-Prinzipien. Der Fokus liegt hier nicht auf Software selbst,
|
||||
sondern auf eine Nutzung von Software die ein Äquivalent zur Nutzung von
|
||||
FAIR-Daten darstellt.
|
||||
|
||||
:::
|
||||
|
||||
::: {.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
|
||||
Zitierbarkeit.
|
||||
|
||||
:::
|
||||
|
||||
Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von
|
||||
|
||||
- Reproduzierbarkeit (Installation, Daten, Beispiele),
|
||||
- Offenheit (Lizenz, offene Formate) und
|
||||
- Nachhaltigkeit (Versionierung, Langlebigkeit der Doku).
|
||||
|
||||
Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie
|
||||
automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche
|
||||
Softwarepraxis.
|
||||
|
||||
### Nutzungshilfen außerhalb der Dokumentation
|
||||
|
||||
Falls Ihre Software ein **Command-Line Interface (CLI)** hat, stellen Sie
|
||||
@ -565,36 +569,10 @@ zumindest ein kleiner _Help_-Abschnitt im Handbuch vorhanden sein. Diese
|
||||
eingebetteten Hilfen ersetzen keine ausführliche Dokumentation, aber sie senken
|
||||
die Schwelle für alltägliche Fragen.
|
||||
|
||||
### Prinzipien: FAIR und ENDINGS
|
||||
|
||||
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}
|
||||
|
||||
Die ENDINGS-Prinzipien für digitale Projekte betonen insbesondere die Bedeutung
|
||||
von Dokumentation für Datenstrukturen, offenen Lizenzen, statischen Outputs und
|
||||
Zitierbarkeit. Unsere Empfehlungen, etwa ein statisches Markdown-README
|
||||
beizulegen, die Datenmodell-Doku nicht auszulagern oder Zitationsangaben zu
|
||||
machen, setzen genau diese Vorgaben um.
|
||||
|
||||
:::
|
||||
|
||||
Gute Dokumentation bedeutet daher u.a. die Verdeutlichung und Sicherstellung von
|
||||
|
||||
- Reproduzierbarkeit (Installation, Daten, Beispiele),
|
||||
- Offenheit (Lizenz, offene Formate) und
|
||||
- Nachhaltigkeit (Versionierung, Langlebigkeit der Doku).
|
||||
|
||||
Indem Sie also diesem Anforderungskatalog folgen, berücksichtigen Sie
|
||||
automatisch wichtige anerkannte Prinzipien für gute wissenschaftliche
|
||||
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
|
||||
@ -612,19 +590,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
|
||||
@ -689,7 +659,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.
|
||||
@ -726,10 +696,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.
|
||||
|
||||
:::
|
||||
|
||||
@ -747,9 +718,10 @@ enthält. Für kleine Scripte genügen ggf. Modul- oder Abschnittskommentare.
|
||||
|
||||
Wichtig ist Konsistenz im Stil – halten Sie sich an Konventionen Ihres
|
||||
Ökosystems (z. B. [Google Style Guide](https://google.github.io/styleguide/) für
|
||||
Python Docstrings oder entsprechende Formatvorgaben für andere Sprachen).
|
||||
Verlinken sie diese Styleguides in der README. Sogenannte Linting-Tools, wie
|
||||
etwa **[pylint][]**, können die Verwendung erzwingen.
|
||||
Python Docstrings oder entsprechende Formatvorgaben für andere
|
||||
Sprachen)[@JimenezEtAl2017FourSimpleRecommendations]. Verlinken sie diese
|
||||
Styleguides in der README. Sogenannte Linting-Tools, wie etwa **[pylint][]**,
|
||||
können die Verwendung erzwingen.
|
||||
|
||||
Mit Tools, wie **[Sphinx][]**, **[Javadoc][]**, **[Doxygen][]**,
|
||||
**[MkDocs][]**,**[pdoc][]** und vielen weiteren, können aus Docstrings
|
||||
@ -758,15 +730,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.
|
||||
|
||||
@ -787,7 +753,7 @@ Codeversion immer eine aktuelle Doku hat_.
|
||||
Schlussendlich muss aber das Level an Automation für jedes Projekt individuell
|
||||
abgewogen werden.
|
||||
|
||||
## Best Practices, Vorlagen und Checklisten
|
||||
## Checklisten und Vorlagen
|
||||
|
||||
Um zu entscheiden, _was_ dokumentiert wird (und was _nicht_), helfen etablierte
|
||||
**Best Practices** sowie Vorlagen aus der Community. Im Folgenden sind einige
|
||||
@ -846,6 +812,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
|
||||
@ -869,7 +845,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}
|
||||
|
||||
@ -918,17 +894,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
|
||||
@ -953,9 +939,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/
|
||||
|
||||
Reference in New Issue
Block a user