mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-07 17:44:01 +00:00
added/formatted background
This commit is contained in:
Nicole Dresselhaus
parent
2300bbdbd2
commit
bb661ce672
3041
background/BACKGROUND.html
Normal file
3041
background/BACKGROUND.html
Normal file
File diff suppressed because one or more lines are too long
828
background/BACKGROUND.md
Normal file
828
background/BACKGROUND.md
Normal file
@ -0,0 +1,828 @@
|
||||
---
|
||||
tags:
|
||||
- Writing
|
||||
cssclasses:
|
||||
- table-wide
|
||||
- table-wrap
|
||||
title:
|
||||
"Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital
|
||||
Humanities)"
|
||||
description: |
|
||||
Ein Überblick und Best Practices für die Dokumantation von Forschungssoftware.
|
||||
abstract: |
|
||||
Diese Dokumentation fasst zusammen, welche wissenschaftlichen Konzepte,
|
||||
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
|
||||
authors:
|
||||
- name: Nicole Dresselhaus
|
||||
affiliation:
|
||||
- name: Humboldt-Universität zu Berlin
|
||||
url: https://hu-berlin.de
|
||||
email: nicole.dresselhaus@hu-berlin.de
|
||||
correspondence: true
|
||||
orcid: 0009-0008-8850-3679
|
||||
roles:
|
||||
- Conceptualization
|
||||
- Supervision
|
||||
- Validation
|
||||
- "Writing – review & editing"
|
||||
- name: GPT-4.5
|
||||
url: https://chatgpt.com
|
||||
affiliation:
|
||||
- name: OpenAI
|
||||
url: https://openai.com
|
||||
roles:
|
||||
- investigation
|
||||
- "Writing – original draft"
|
||||
citation: true
|
||||
google-scholar: true
|
||||
fileClass: authored
|
||||
bibliography:
|
||||
- background.bib
|
||||
citation-style: springer-humanities-brackets
|
||||
format:
|
||||
html:
|
||||
embed-resources: true
|
||||
link-external-icon: true # externe links markieren
|
||||
link-external-newwindow: true # externe linkn in neuem Fenster öffnen
|
||||
toc-location: left # table of contents links (oder rechts)
|
||||
toc: true
|
||||
citation-location: document
|
||||
reference-location: margin # fußnoten im Margin (falls gewünscht)
|
||||
mermaid:
|
||||
theme: default
|
||||
theme:
|
||||
- themes/nfdi.scss # theme aus ./themes/ auswählen
|
||||
---
|
||||
|
||||
## Einleitung
|
||||
|
||||
Die **Dokumentation von Forschungssoftware** ist entscheidend, um
|
||||
wissenschaftliche Ergebnisse nachvollziehbar und Software für andere nutzbar zu
|
||||
machen. Insbesondere in den Digital Humanities (etwa in der
|
||||
Geschichtswissenschaft) entwickeln Forschende neben Forschung und Lehre oft
|
||||
eigene Software – meist unter hohem Zeitdruck und ohne formale Ausbildung in
|
||||
Softwareentwicklung. Häufig bleibt die Dokumentation deshalb minimal oder
|
||||
unvollständig, was dazu führt, dass andere (und sogar die Autor\*innen selbst)
|
||||
viel Zeit aufwenden müssen, um den Code zu verstehen und anzuwenden. Dabei gilt
|
||||
gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware
|
||||
**auffindbar, nachvollziehbar und wiederverwendbar** zu machen.
|
||||
|
||||
[Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien
|
||||
[@prlic2012ten; @wilson2017good; @katz2021open;
|
||||
@endings2020principles].]{.aside}
|
||||
|
||||
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
|
||||
insbesondere die Prinzipien des _Endings-Projekts_ für digitale Langlebigkeit
|
||||
[@endings2020principles]. 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. Im
|
||||
Folgenden werden die Anforderungen an Inhalt, Format und Umfang der
|
||||
Dokumentation definiert, geeignete (teil-)automatisierte Dokumentationswerkzeuge
|
||||
diskutiert und Best Practices in Form von Vorlagen und Checklisten vorgestellt.
|
||||
|
||||
## Inhaltliche Anforderungen an die Dokumentation
|
||||
|
||||
Ein zentrales Problem in der Dokumentation wissenschaftlicher Software ist oft
|
||||
das fehlende _Big Picture_, also eine klare Darstellung des _Was_ und _Warum_.
|
||||
Die Dokumentation sollte daher alle **Informationen abdecken, die zum Verstehen,
|
||||
Nutzen und Weiterentwickeln der Software nötig sind**. Insbesondere sind
|
||||
folgende Inhalte essenziell:
|
||||
|
||||
### Ziel und Zweck der Software (Statement of Need)
|
||||
|
||||
Beschreiben Sie _was die Software tut_ und _warum sie entwickelt wurde_. Nennen
|
||||
Sie den wissenschaftlichen Zweck, das Forschungsproblem oder die Fragestellung,
|
||||
die mit der Software adressiert wird, sowie die _Zielgruppe_ (wer soll sie
|
||||
nutzen?). Dieser Kontext hilft anderen, den Nutzen der Software einzuschätzen.
|
||||
Beispiel: _“Dieses Tool extrahiert Personen-Netzwerke aus historischen
|
||||
Briefkorpora, um sozialwissenschaftliche Analysen zu ermöglichen.”_ Eine klare
|
||||
Problem- und Zielbeschreibung richtet sich auch nach dem Umfeld ähnlicher
|
||||
Lösungen – falls es bereits etablierte Tools gibt, sollte die Dokumentation die
|
||||
eigene Herangehensweise einordnen (z. B. was die Software anders oder besser
|
||||
macht).
|
||||
|
||||
### Input-/Output-Spezifikation und Datenbeschreibung
|
||||
|
||||
Dokumentieren Sie alle _Eingabeformate, Ausgabedaten und verwendeten
|
||||
Datensätze_. Nutzer\*innen müssen wissen, welche Daten die Software erwartet
|
||||
(Dateiformate, Schnittstellen, Parameter) und welche Ergebnisse sie produziert.
|
||||
Idealerweise werden Beispiele angegeben: z. B. Beispiel-Dateien oder -Parameter
|
||||
und die korrespondierende Ausgabe. Falls die Software mit bestimmten
|
||||
Forschungsdaten arbeitet, beschreiben Sie diese Daten und ihre Struktur. Dies
|
||||
umfasst die **Datenmodelle** (etwa wichtige Felder, deren Bedeutung und
|
||||
kontrollierte Vokabulare) und Annahmen über die Daten. Gemäß den
|
||||
ENDINGS-Prinzipien sollte die Datenstruktur in einem _statischen Dokument_
|
||||
festgehalten und der Software beigelegt sein – so bleibt nachvollziehbar, wie
|
||||
die Software die Daten interpretiert. Eine Tabelle oder Auflistung der
|
||||
Eingabefelder und Ausgabegrößen mit kurzen Beschreibungen erhöht die Klarheit.
|
||||
[Beispiel: _“Eingabedatei: CSV mit Spalten `Autor`, `Empfänger`, ...; Ausgabe:
|
||||
JSON-Datei mit Netzwerk-Metriken pro Briefwechsel.”_]{.aside}
|
||||
|
||||
### Code-Abhängigkeiten und technische Voraussetzungen
|
||||
|
||||
Listen Sie alle _Abhängigkeiten_ (Dependencies) der Software auf. Dazu gehören
|
||||
verwendete Programmiersprachen/Versionen, erforderliche Bibliotheken oder
|
||||
Frameworks, und sonstige Systemvoraussetzungen (z. B. Betriebssystem,
|
||||
Mindesthardware, Datenbank-Versionen). Wichtig ist, **wie** diese Abhängigkeiten
|
||||
installiert werden können. Optimal ist eine automatisierte Installationsroutine
|
||||
(z. B. ein `requirements.txt` für Python oder ein Paketmanager-Befehl). In jedem
|
||||
Fall sollte die Dokumentation mindestens
|
||||
Schritt-für-Schritt-Installationsanleitungen enthalten (inklusive evtl.
|
||||
benötigter Vorkenntnisse, z. B. _“Python 3 erforderlich”_). [Beispiel:
|
||||
_“Benötigt Python 3.9 und die Bibliotheken Pandas und NetworkX. Installation:
|
||||
`pip install -r requirements.txt`.”_ Falls spezielle technische Voraussetzungen
|
||||
bestehen – etwa Zugriff auf bestimmte Hardware, ein Hochleistungsrechner oder
|
||||
große Speicherkapazitäten – sind diese zu nennen.]{.aside}
|
||||
|
||||
- **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).
|
||||
[Faustregel: **Zeigen statt nur beschreiben** – konkrete Anwendungsfälle in
|
||||
der Doku verankern.]{.aside}
|
||||
|
||||
### Wissenschaftlicher Hintergrund und theoretischer Kontext
|
||||
|
||||
Da es sich um Forschungssoftware handelt, sollten Sie den _wissenschaftlichen
|
||||
Kontext_ 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. Wichtig ist, dass die
|
||||
Dokumentation den **Brückenschlag zwischen Code und Forschung** herstellt. Da
|
||||
viele Wissenschaftler\*innen zentrale Aspekte lieber in ihren Artikeln
|
||||
dokumentieren, sollte in der Software-Dokumentation zumindest eine
|
||||
Zusammenfassung mit Querverweis erfolgen. So wissen Nutzer\*innen, unter welchen
|
||||
Annahmen oder Theorien das Tool funktioniert. [Dieser Hintergrundteil
|
||||
unterscheidet Forschungssoftware-Dokumentation von rein kommerzieller
|
||||
Dokumentation: Es geht nicht nur um _wie_ man das Tool benutzt, sondern auch
|
||||
_warum_ es so funktioniert (Stichwort Nachvollziehbarkeit).]{.aside}
|
||||
|
||||
### Bekannte Limitationen, Annahmen und Fehlermeldungen
|
||||
|
||||
Geben Sie ehrlich Auskunft über die _Grenzen der Software_. Welche Fälle werden
|
||||
**nicht** abgedeckt? Welche Annahmen über die Daten oder Anwendungsszenarien
|
||||
werden getroffen? Dokumentieren Sie bekannte Probleme oder Einschränkungen
|
||||
(z. B. _“funktioniert nur für Deutschsprachige Texte”, “maximale Datenmenge 1
|
||||
Mio. Datensätze, da Speicherbegrenzung”_). Solche Hinweise verhindern
|
||||
Fehlanwendungen und sparen Nutzern Zeit. Falls es bekannte **Bugs oder
|
||||
Workarounds** gibt, sollten diese ebenfalls (etwa in einer FAQ oder einem
|
||||
Abschnitt "Bekannte Probleme") erwähnt werden. Eine transparente Auflistung von
|
||||
Limitationen erhöht die Vertrauenswürdigkeit und hilft anderen, die Ergebnisse
|
||||
richtig einzuordnen. Auch **aussagekräftige Fehlermeldungen** im Programm selbst
|
||||
sind eine Form von Dokumentation: Sie sollten nicht nur kryptisch abbrechen,
|
||||
sondern dem/der Anwender\*in idealerweise mitteilen, was schiefging und wie es
|
||||
behoben werden kann (z. B. _“Fehler: Ungültiges Datum im Feld XY – bitte Format
|
||||
TT/MM/JJJJ verwenden.”_). Solche in den Code integrierten Hinweise ergänzen die
|
||||
schriftliche Dokumentation und tragen zur besseren Nutzbarkeit bei.
|
||||
|
||||
### Weiterentwicklung und Beitragsmöglichkeiten
|
||||
|
||||
Obwohl viele Digital-Humanities-Tools primär von Einzelpersonen genutzt werden,
|
||||
sollte dennoch angegeben werden, wie andere ggf. _zur Software beitragen oder
|
||||
Support erhalten_ können. Ein kurzer Hinweis auf den Issue-Tracker (z. B.
|
||||
_“Fehler bitte über GitHub-Issues melden”_) oder auf die Kontaktmöglichkeit zum
|
||||
Autor (E-Mail) gehört dazu. Ebenso können **Community Guidelines** skizziert
|
||||
werden: etwa Codierstandards 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 aber Offenheit und sorgt dafür, dass im Falle von
|
||||
Rückfragen die Hürde für Kontaktaufnahme niedrig ist.]{.aside}
|
||||
|
||||
### 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. 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[@smith2016software]. Schließlich
|
||||
ist es sinnvoll, eine **Versionsnummer** der Software zu nennen (idealerweise in
|
||||
README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die
|
||||
Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen
|
||||
gibt. Diese Praxis entspricht auch den ENDINGS-Prinzipien, die verlangen, dass
|
||||
jede veröffentlichte Version eindeutig erkennbar ist und zitiert werden kann.
|
||||
|
||||
### Zusammenfassung der inhaltlichen Anforderungen
|
||||
|
||||
Zusammengefasst sollte die Dokumentation alle **W-Fragen** beantworten: _Was_
|
||||
tut die Software, _warum_ wurde sie geschrieben (wissenschaftlicher Zweck),
|
||||
_wer_ soll sie nutzen, _wie_ wird sie benutzt (Inputs, Outputs, Abläufe),
|
||||
_womit_ läuft sie (Umgebung/Abhängigkeiten), _unter welchen Bedingungen_
|
||||
(Annahmen/Limitationen) und _wohin_ können sich Nutzer wenden
|
||||
(Support/Zitation). All diese Punkte sorgen für **Nachvollziehbarkeit** (im
|
||||
Sinne von Reproduzierbarkeit der Ergebnisse) und **Weiterverwendbarkeit** (im
|
||||
Sinne von Adaptierbarkeit der Software für neue Kontexte).
|
||||
|
||||
## Format und Struktur der Dokumentation
|
||||
|
||||
Für Forschende ohne viel Ressourcen muss die Dokumentation **einfach zugänglich,
|
||||
leicht pflegbar und ohne Spezialsoftware** erstellbar sein. Daher empfiehlt es
|
||||
sich, auf **leichte Formate** und eine klare Struktur zu setzen:
|
||||
|
||||
### `README.md` als zentrales Dokument
|
||||
|
||||
Die Hauptdokumentation sollte als README in Markdown-Format im Hauptverzeichnis
|
||||
des Code-Repositoriums liegen. Dieses README fungiert als “Startseite” des
|
||||
Projekts und enthält idealerweise eine komprimierte Übersicht aller wichtigen
|
||||
Punkte: Zweck der Software, Kurzbeschreibung, Installation, kurzer
|
||||
Nutzungsbeispiel, Kontakt/Lizenz. Auf Plattformen wie GitHub, GitLab etc. wird
|
||||
die README automatisch angezeigt, was die Sichtbarkeit erhöht. Die Vorteile von
|
||||
**Markdown** sind die einfache Lesbarkeit in Rohform, die breite Unterstützung
|
||||
(auch in Renderern wie GitHub-Webansicht) und die Eignung für Versionierung
|
||||
(Textdatei im Git). So bleibt die Dokumentation eng mit dem Code verzahnt und
|
||||
unter Versionskontrolle – ein Prinzip, das auch von ENDINGS propagiert wird
|
||||
(Dokumentation soll statisch und zusammen mit den Daten/Code abgelegt werden).
|
||||
|
||||
### Strukturierte Unterteilung in weitere Dateien/Abschnitte
|
||||
|
||||
::: {.column-margin}
|
||||
|
||||
```plain
|
||||
example-project/
|
||||
├── README.md
|
||||
├── CONTRIBUTING.md (optional)
|
||||
├── CHANGELOG.md (optional)
|
||||
├── CITATION.md (oder CITATION.cff)
|
||||
├── LICENSE
|
||||
├── data/ (optional)
|
||||
│ └── sample_data.csv
|
||||
├── docs/ (optional)
|
||||
│ ├── INSTALL.md
|
||||
│ └── USAGE.md
|
||||
├── examples/ (optional)
|
||||
│ └── example_workflow.ipynb
|
||||
└── src/
|
||||
├── script.py
|
||||
└── module/
|
||||
└── helper.py
|
||||
```
|
||||
|
||||
Beispielhafter Struktur eines Code-Repositories
|
||||
|
||||
:::
|
||||
|
||||
Sollte die Dokumentation umfangreicher sein, ist es sinnvoll, sie in logisch
|
||||
getrennte Abschnitte aufzuteilen. Dies kann innerhalb der README durch
|
||||
Überschriften geschehen oder durch **zusätzliche Markdown-Dateien** im
|
||||
Repository (z. B. eine `INSTALL.md` für ausführliche Installationshinweise, eine
|
||||
`USAGE.md` oder `TUTORIAL.md` für detaillierte Benutzeranleitungen, eine
|
||||
`CHANGELOG.md` für Changelog etc.). Eine gängige Struktur ist z. B.:
|
||||
|
||||
- `README.md` – Überblick (Ziel, Installation, kurzes Beispiel, Lizenz/Zitation)
|
||||
- `docs/` Verzeichnis mit weiteren .md-Dateien für tiefergehende Dokumentation
|
||||
(optional)
|
||||
- `CONTRIBUTING.md` – Hinweise für Beiträger (falls relevant)
|
||||
- `LICENSE` – Lizenztext
|
||||
- `CITATION.cff` oder `CITATION.md` – wie zu zitieren.
|
||||
|
||||
Diese Dateien sollten konsistent formatiert und benannt sein, damit sie leicht
|
||||
auffindbar sind. Sie kommen ohne spezielle Tools aus – ein einfacher Texteditor
|
||||
genügt zum Bearbeiten. Auch **Wiki-Seiten** (etwa in GitHub) können genutzt
|
||||
werden, sind aber weniger dauerhaft versioniert im Vergleich zu Dateien im
|
||||
Code-Repository selbst. Die Dokumentation sollte möglichst _im Repository_
|
||||
selbst liegen, um sicherzustellen, dass sie gemeinsam mit dem Code versioniert,
|
||||
verteilt und archiviert wird. Externe Dokumentationswebsites sind für kleine
|
||||
Projekte oft Overkill und können im schlimmsten Fall verwaisen.
|
||||
|
||||
### Keine proprietären Formate oder Abhängigkeit von Werkzeugen
|
||||
|
||||
Um Hürden für die Erstellung und Nutzung der Dokumentation gering zu halten,
|
||||
sollte auf gängige, offene Formate gesetzt werden (Plaintext, Markdown,
|
||||
reStructuredText). Vermeiden Sie nach Möglichkeit Formate wie Word-Dokumente
|
||||
oder PDF als primäre Dokumentationsquelle – solche Formate sind nicht
|
||||
diff-freundlich, erschweren Zusammenarbeits-Workflows und sind meist nicht Teil
|
||||
des Versionskontrollsystems. Ein Markdown-Dokument hingegen kann gemeinsam mit
|
||||
dem Code gepflegt werden, und Änderungen sind transparent nachvollziehbar. Zudem
|
||||
erlauben offene Formate eine leichtere **Langzeitarchivierung**: Gemäß
|
||||
Endings-Prinzip sollten Informationsressourcen in langfristig lesbaren Formaten
|
||||
vorliegen. Markdown/Plaintext erfüllt diese Bedingung (im Gegensatz etwa zu
|
||||
einer Datenbank-gestützten Wissensbasis oder einem proprietären Wiki, das in 10
|
||||
Jahren evtl. nicht mehr läuft). Im Sinne der _Digital Longevity_ ist eine
|
||||
**statische HTML- oder PDF-Version** der Dokumentation (automatisch generiert
|
||||
aus Markdown) als Teil der Release-Artefakte sinnvoll – so kann z. B. in jeder
|
||||
veröffentlichten Version ein PDF-Handbuch beigelegt werden, das später zitiert
|
||||
oder referenziert werden kann. **Wichtig ist aber, dass die Quelle der Wahrheit
|
||||
immer die im Repository gepflegte Doku bleibt.**
|
||||
|
||||
### Übersichtlichkeit und Navigierbarkeit
|
||||
|
||||
Strukturieren Sie die Dokumentation mit klaren Überschriften und Listen, damit
|
||||
Leser schnell die gesuchten Informationen finden. Eine **logische Gliederung**
|
||||
(wie in diesem Katalog: Einführung, Anforderungen, Installation, Nutzung,
|
||||
Hintergrund, etc.) hilft unterschiedlichen Nutzergruppen gezielt das Relevante
|
||||
zu finden. Für längere Dokumente kann ein Inhaltsverzeichnis oder eine
|
||||
Abschnittsübersicht am Anfang nützlich sein. Markdown bietet z. B. automatische
|
||||
Toc-Generierung auf manchen Plattformen. Achten Sie darauf, pro Abschnitt nur
|
||||
zusammenhängende Informationen zu behandeln (z. B. alles zu Installation an
|
||||
einem Ort). Wiederholungen sollten vermieden werden: lieber an einer Stelle
|
||||
ausführlich dokumentieren und sonst darauf verweisen, um Konsistenzprobleme zu
|
||||
vermeiden (_"Don’t Repeat Yourself"_ gilt auch für Dokumentation). Bei ähnlichen
|
||||
Projekten können Sie sich an bestehenden **Dokumentationsvorlagen** orientieren:
|
||||
Viele erfolgreiche Open-Source-Projekte haben auf GitHub eine ähnliche
|
||||
README-Struktur, die als informelles Template dienen kann.
|
||||
|
||||
### Beispiele, Codeblöcke und ggf. Abbildungen einbinden
|
||||
|
||||
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
|
||||
(etwa ein Diagramm der Datenpipeline, ein Screenshot der Benutzeroberfläche,
|
||||
etc.). Achten Sie dabei auf Dateigrößen und Formate (Bilder als PNG/JPG,
|
||||
Diagramme wenn möglich als SVG für Langlebigkeit). Falls Diagramme der
|
||||
Architektur oder Workflow-Abbildungen hilfreich sind, können diese mit simplen
|
||||
Mitteln erstellt werden (zur Not handgezeichnet und abfotografiert, besser
|
||||
jedoch mit Tools wie mermaid.js Diagrammen in Markdown oder Graphviz). Diese
|
||||
Visualisierungen sind jedoch nur dann einzusetzen, wenn sie echten Mehrwert
|
||||
bieten und ohne komplexe Build-Prozesse eingebunden werden können. Im Zweifel
|
||||
hat textuelle Beschreibung Vorrang, um nicht vom **prinzip “keep it simple”**
|
||||
abzuweichen.
|
||||
|
||||
### Fazit Format und Struktur
|
||||
|
||||
Insgesamt gilt: **Die Dokumentation sollte im gleichen Repository leben wie der
|
||||
Code, klar strukturiert und in einem einfach handhabbaren Format vorliegen.**
|
||||
Sie soll ohne spezielle Umgebung lesbar sein – ein Nutzer, der das Repository
|
||||
klont oder herunterlädt, muss sofort Zugang zur Dokumentation haben. 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.
|
||||
|
||||
## Umfang und Fokus der Dokumentation
|
||||
|
||||
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.
|
||||
|
||||
Ein effizienter Umfang lässt sich erreichen, indem man sich auf die oben
|
||||
genannten Kernpunkte konzentriert und Ablenkendes weglässt. Dokumentieren Sie
|
||||
**alles, was für Nachvollziehbarkeit und Wiederverwendung nötig ist, und skippen
|
||||
Sie alles andere**. Zum Beispiel muss nicht jeder interne Programmiertrick
|
||||
erläutert werden – Quellcode-Kommentare richten sich an Entwickler, während die
|
||||
Nutzerdokumentation sich auf Nutzung und Kontext beschränkt. Verzichten Sie auf
|
||||
seitenlange Theorieableitungen (verweisen Sie stattdessen auf Papers) und auf
|
||||
generische Erklärungen bekannter Technologien (man muss Git oder Python nicht in
|
||||
der Doku erklären, sondern kann referenzieren). Halten Sie auch die Sprache
|
||||
prägnant: kurze Absätze, Listen und einfache Sätze erhöhen die Lesbarkeit.
|
||||
Fachtermini aus dem jeweiligen wissenschaftlichen Bereich dürfen verwendet
|
||||
werden, aber erklären Sie sie, falls die Zielnutzer sie evtl. nicht kennen.
|
||||
|
||||
**Priorisierung:** Beginnen Sie mit einer Minimaldokumentation, die alle
|
||||
Schlüsselaspekte abdeckt (_“keine Dokumentation”_ ist keine Option). _Good
|
||||
Enough Practices_ 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. 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 _klein_ 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).
|
||||
|
||||
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. 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?** Wenn ja, ist der Detailgrad angemessen. Wenn die Person hingegen
|
||||
nach 10 Seiten immer noch nicht weiß, wie sie loslegen soll, muss die Doku
|
||||
fokussierter werden. 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.
|
||||
|
||||
Ein weiterer Tipp zur Effizienz: Nutzen Sie **Verweise und vorhandene
|
||||
Ressourcen**. 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. 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.
|
||||
|
||||
Zum Fokus gehört auch, zwischen **Nutzerdokumentation und
|
||||
Entwicklerdokumentation** zu unterscheiden. Dieser Katalog adressiert primär die
|
||||
Nutzerdokumentation (für Endnutzer und für die Autoren selbst, wenn sie das Tool
|
||||
später wieder anfassen). Entwicklerdokumentation (z. B. detaillierte
|
||||
API-Dokumente, Code-Kommentare, technische Architektur) kann separat gehalten
|
||||
werden, sofern nötig, um den Hauptnutzerfluss nicht zu überfrachten. Für viele
|
||||
kleine Forschungssoftware-Projekte sind ausführliche Entwicklerdokus 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.
|
||||
|
||||
Abschließend sei betont: Ein kompakter, zielgerichteter Dokumentsatz, der genau
|
||||
die relevanten Infos liefert, erhöht die Wahrscheinlichkeit, dass er
|
||||
**aktualisiert und genutzt** wird. Umfangmonster schrecken ab und veralten
|
||||
schneller. Halten Sie die Dokumentation deshalb so **knapp wie möglich, aber so
|
||||
ausführlich wie nötig** – ganz im Sinne von Einsteins Prinzip, Dinge so einfach
|
||||
wie möglich zu machen, aber nicht einfacher.
|
||||
|
||||
## (Teil-)automatisierte Dokumentationswerkzeuge
|
||||
|
||||
Die Dokumentationslast lässt sich durch den Einsatz geeigneter Werkzeuge
|
||||
erheblich senken. Gerade Forschende, die alleine programmieren, können von
|
||||
**(teil-)automatisierter Dokumentation** 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,
|
||||
_wann_ ihr Einsatz sinnvoll oder notwendig ist:
|
||||
|
||||
### Docstrings und API-Dokumentationsgeneratoren
|
||||
|
||||
Nutzen Sie die Möglichkeit, Dokumentation _direkt im Quellcode_ unterzubringen,
|
||||
z. B. in Form von **Docstrings** (mehrzeilige Strings in Funktionen/Klassen bei
|
||||
Python, Roxygen-Kommentare in R, Javadoc-Kommentare in Java, etc.). 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 _jede
|
||||
wichtige Funktion, Klasse oder Modul_ mit einem kurzen Docstring, der Zweck,
|
||||
Parameter, Rückgaben und ggf. Beispiele 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** für Python
|
||||
Docstrings oder entsprechende Formatvorgaben für andere Sprachen). Mit Tools wie
|
||||
**Sphinx** (für Python, aber grundsätzlich sprachunabhängig) können aus
|
||||
Docstrings automatisiert Webseiten oder PDF-Handbücher generiert werden. Sphinx
|
||||
liest z. B. die Python-Docstrings und erzeugt daraus strukturiert eine
|
||||
Dokumentation; Erweiterungen wie _napoleon_ erlauben es, Google- oder
|
||||
Numpy-Style-Dokumentation direkt zu verarbeiten.
|
||||
|
||||
::: {.column-margin}
|
||||
|
||||
Ähnliche Generatoren gibt es für nahezu alle Sprachen: **Javadoc** für Java,
|
||||
**Doxygen** für C/C++ (und viele andere Sprachen), **MkDocs** oder _pdoc_ für
|
||||
Python, etc.
|
||||
|
||||
:::
|
||||
|
||||
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. **Verpflichtend** wird dieser
|
||||
Ansatz etwa, wenn Sie ein Bibliothekspaket veröffentlichen (z. B. ein R-Package
|
||||
in CRAN oder Python-Package auf PyPI) – dort sind Docstrings und generierte
|
||||
Dokumentation quasi Standard. Für ein einmaliges Analyse-Skript in den Digital
|
||||
Humanities ist eine voll ausgebaute API-Doku vielleicht nicht nötig; hier reicht
|
||||
möglicherweise ein inline kommentierter Code. Doch sobald Funktionen von anderen
|
||||
aufgerufen oder das Projekt von mehreren entwickelt wird, sollte ein
|
||||
Dokumentationstool in Betracht gezogen werden, um den Aufwand gering zu halten
|
||||
und Einheitlichkeit zu gewährleisten.
|
||||
|
||||
### Jupyter Notebooks und literate programming
|
||||
|
||||
Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind
|
||||
**Jupyter Notebooks** bzw. R Markdown Notebooks [@maria2019jupyter]. Diese
|
||||
erlauben es, _ausführbaren Code mit erklärendem Text und Visualisierungen_ in
|
||||
einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei
|
||||
leisten: (1) als **Tutorials/Beispiel-Workflows**, die Nutzer interaktiv
|
||||
nachvollziehen können, und (2) als **Reproduzierbarkeits-Dokumentation** für
|
||||
analytische Prozesse. Wenn Ihre Forschungssoftware z. B. eine Bibliothek ist,
|
||||
könnten Sie ein Notebook bereitstellen, das einen typischen Anwendungsfall
|
||||
durchspielt (inklusive Daten-Loading, Aufruf der Funktionen, Darstellung der
|
||||
Ergebnisse).
|
||||
|
||||
Notebooks senken die Hürde, weil Nutzer direkt experimentieren können, und
|
||||
fördern transparente Forschung, da Code, Ergebnisse und Beschreibung
|
||||
zusammenfließen. Sie sind daher sinnvoll, **wenn der Hauptanwendungsfall die
|
||||
Durchführung von Analysen oder Datenverarbeitungen ist**, die man Schritt für
|
||||
Schritt demonstrieren kann.
|
||||
|
||||
::: {.callout-warning}
|
||||
|
||||
Notebooks erfordern allerdings eine lauffähige Umgebung – das heißt, Sie müssen
|
||||
darauf achten, dass alle Abhängigkeiten im Notebook deklariert sind und die
|
||||
Daten zugänglich sind. Es hat sich gezeigt, dass Notebooks aus Publikationen oft
|
||||
nicht ohne Weiteres laufen, weil Pfade, Datenquellen oder spezielle Umgebungen
|
||||
fehlen. Deshalb: Wenn Sie Notebooks als Doku nutzen, stellen Sie sicher, dass
|
||||
sie _leicht ausführbar_ sind (z. B. durch Bereitstellen von Umgebungsdateien wie
|
||||
`environment.yml` oder Dockerfiles, kleinen Beispieldatensätzen und klaren
|
||||
Anweisungen im Notebook). Ggf. kann man Notebooks auch in reine Markdown/HTML
|
||||
exportieren und dem Repo beilegen, damit zumindest statisch die Inhalte
|
||||
einsehbar sind.
|
||||
|
||||
:::
|
||||
|
||||
**Wann sind Notebooks verpflichtend?** – Nie im strengen Sinne, aber sie sind
|
||||
quasi Goldstandard, um wissenschaftliche Analysen nachvollziehbar zu machen. In
|
||||
Projekten, wo es um Data Science Workflows oder interaktive Exploration geht,
|
||||
sollten Notebooks stark erwogen werden, während für ein reines Tool/Script eine
|
||||
gut geschriebene README mit Beispielausgabe ausreichend sein kann.
|
||||
|
||||
### Sphinx/MkDocs/Doxygen (statische Dokumentationswebseiten)
|
||||
|
||||
Für umfangreichere Projekte oder solche mit eigener Website kann es sinnvoll
|
||||
sein, eine **Dokumentationswebsite** zu generieren. Tools wie _Sphinx_ (zusammen
|
||||
mit ReadTheDocs für Hosting) oder _MkDocs_ erlauben es, aus
|
||||
Markdown/reStructuredText-Dateien einen ansprechend formatierten
|
||||
HTML-Dokumentationssatz zu bauen. Der Vorteil ist, dass man eine durchsuchbare,
|
||||
verlinkte Doku bekommt, oft mit schönem Layout und zusätzlicher Navigation. Mit
|
||||
_Continuous Integration_ lassen sich diese Seiten bei jedem Git-Push automatisch
|
||||
aktualisieren. Für die Nachhaltigkeit (ENDINGS-Prinzip) ist wichtig, dass diese
|
||||
Webseiten statisch sind – d.h. sie funktionieren ohne Server-Backends und
|
||||
bleiben auch offline nutzbar. Sphinx erfüllt dies, indem es reine HTML-Seiten
|
||||
erzeugt. Solche Tools sind **sinnvoll, wenn die Dokumentation sehr groß oder
|
||||
öffentlich weit verbreitet** ist – z. B. wenn Ihre Software von vielen genutzt
|
||||
wird und Sie ein professionelles Auftreten wünschen, oder wenn Sie die Doku als
|
||||
PDF veröffentlichen möchten. [In kleinen DH-Projekten ist es oft nicht nötig,
|
||||
extra eine Webseite zu hosten; dennoch kann Sphinx auch lokal HTML/PDF erzeugen,
|
||||
was man dem Repo beilegen kann.]{.aside}
|
||||
|
||||
**Verpflichtend** ist so ein Tool selten, höchstens wenn Förderprogramme oder
|
||||
Journals ein dokumentationsseitiges HTML-Manual verlangen. Wenn Sie jedoch
|
||||
planen, Ihre Software z. B. über Jahre zu pflegen und ggf. einem Journal wie
|
||||
JOSS vorzustellen, dann erwartet die Community meist, dass zumindest eine
|
||||
Sphinx/Doxygen-Doku für die API existiert. Als Daumenregel: ab einer Codebasis >
|
||||
einige tausend Zeilen oder > 5 Module lohnt es sich, eine generierte
|
||||
Dokumentation bereitzustellen, um den Überblick zu behalten.
|
||||
|
||||
### In-Code Hilfefunktionen und CL-Interface Doku
|
||||
|
||||
Falls Ihre Software ein **Command-Line Interface (CLI)** hat, stellen Sie
|
||||
sicher, dass eine eingebaute Hilfe vorhanden ist (z. B. Ausgabe bei `--help`).
|
||||
Viele Nutzer greifen zunächst darauf zurück. Dieses Hilfemenü sollte kurz
|
||||
erläutern, welche Subkommandos oder Optionen existieren. Moderne CLI-Frameworks
|
||||
generieren solche Hilfen oft automatisch aus Ihrem Code (z. B. Click oder
|
||||
argparse in Python erzeugen `--help`-Texte). Nutzen Sie das, um konsistente
|
||||
Infos zu garantieren.
|
||||
|
||||
Für **GUI-Anwendungen** sollten Tooltips, Hilfetexte in der Oberfläche oder
|
||||
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.
|
||||
|
||||
### Versionskontrolle und kontinuierliche Dokumentationspflege
|
||||
|
||||
Eine Form der _Teil-Automatisierung_ ist es, die Dokumentation an den
|
||||
Entwicklungs-Workflow zu koppeln. So sollte die Dokumentation im selben
|
||||
Versionskontrollsystem (Git) liegen wie der Code, damit Änderungen synchron
|
||||
nachverfolgt werden. Es empfiehlt sich, bei jedem größeren Code-Update zu
|
||||
prüfen, ob die Doku noch stimmt (das kann man sich z. B. als Punkt in
|
||||
Pull-Request-Reviews notieren oder per Issue-Template abfragen). Für Projekte
|
||||
mit Continuous Integration (CI) kann man sogar automatisierte Checks einrichten,
|
||||
die z. B. prüfen, ob die Doku gebaut werden kann oder ob Docstrings fehlen.
|
||||
Einige CI-Skripte generieren bei jedem Commit eine frische Doku (z. B. mittels
|
||||
Sphinx) und veröffentlichen sie – so ist garantiert, dass _die aktuelle
|
||||
Codeversion immer eine aktuelle Doku hat_. [Dieses Level an Automation ist für
|
||||
kleine Projekte evtl. zu viel, aber das **Prinzip “Dokumentation versionieren”**
|
||||
ist allgemeingültig, um die Entwicklungshistorie konsistent zu halten.]{.aside}
|
||||
|
||||
### Spezialfälle
|
||||
|
||||
In bestimmten Fällen gibt es weitere Werkzeuge: z. B. **Doxygen** für
|
||||
automatisierte Code-Diagramme und Querverweise (gerne in C++-Projekten genutzt),
|
||||
oder **Swagger/OpenAPI** für automatische Dokumentation von Web-APIs. Wenn Ihre
|
||||
Forschungssoftware z. B. einen Webservice anbietet, kann Swagger eine
|
||||
interaktive API-Doku erzeugen. Ebenso können **Literatur-Manager** wie Manubot
|
||||
oder RMarkdown Bücher helfen, Code und Text zu integrieren (aber das geht über
|
||||
das hinaus, was die meisten DH-Projekte benötigen). Erwähnenswert ist noch
|
||||
**Jupyter Book** oder R **Bookdown**, womit man umfangreiche narrative
|
||||
Dokumentationen (inkl. Code) als Website/Book erstellen kann – nützlich, falls
|
||||
Ihre Dokumentation eher ein ausführlicher Lehrtext werden soll (z. B. wenn die
|
||||
Software einen ganzen methodischen Ansatz dokumentiert). Für den hier
|
||||
anvisierten Zweck (knackiger Doku-Katalog) sind solche Tools meist zu
|
||||
schwergewichtig.
|
||||
|
||||
### Wann ist was verpflichtend
|
||||
|
||||
Es gibt kein universelles Muss, außer: **Irgendeine Form der Doku ist Pflicht**.
|
||||
Ob Sie nun per Hand Markdown schreiben oder Sphinx einsetzen, hängt von Kontext
|
||||
und Projektgröße ab. Allgemein gilt: Verwenden Sie Automatisierung wo immer
|
||||
möglich, _um sich zu entlasten_, aber vermeiden Sie Overhead durch Tools, die
|
||||
Sie nicht brauchen. Ein einzelnes historisches Analyse-Skript braucht kein
|
||||
Doxygen; ein komplexes DH-Toolkit mit API sollte hingegen Doxygen oder Sphinx
|
||||
nutzen, damit die Nutzer nicht den Code lesen müssen, um Funktionen zu
|
||||
verstehen. Denken Sie daran: _“Die beste Dokumentation ist die, die sich selbst
|
||||
schreibt.”_ – dieses Motto aus der Literatur spielt darauf an, dass wir Tools
|
||||
nutzen sollen, die uns Schreibarbeit abnehmen. Perfekt autonom schreibt sich die
|
||||
Dokumentation zwar nie, aber moderne Werkzeuge können Routineaufgaben (z. B.
|
||||
Inhaltsverzeichnisse, Funktionsreferenzen, Formatierung) automatisieren. Dadurch
|
||||
bleibt Ihnen mehr Zeit für das inhaltliche Fine-Tuning der Texte.
|
||||
|
||||
## Best Practices, Vorlagen und Checklisten
|
||||
|
||||
Um zu entscheiden, _was_ dokumentiert wird (und was nicht), helfen etablierte
|
||||
**Best Practices** sowie Vorlagen aus der Community. Im Folgenden sind einige
|
||||
bewährte Richtlinien zusammengefasst, untermauert von Quellen, die bei der
|
||||
Priorisierung der Dokumentationsinhalte helfen:
|
||||
|
||||
### Orientierung an Nutzerbedürfnissen
|
||||
|
||||
Stellen Sie sich beim Schreiben der Doku die verschiedenen _Nutzerrollen_ vor:
|
||||
**“Zukünftiges Ich”**, **Kolleg\*innen**, **Fachforscher anderer Disziplin** und
|
||||
ggf. **Software-Entwickler, die den Code erweitern**. Jede dieser Gruppen möchte
|
||||
bestimmte Dinge wissen. _Forscher\*innen_ fragen: _Was kann das Tool? Wie
|
||||
benutze ich es? In welchem Kontext steht es?_. _Entwickler\*innen_ 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 (z. B. Code-Struktur,
|
||||
To-do-Liste) können separat oder später ergänzt werden. Halten Sie sich stets
|
||||
vor Augen: **Dokumentation ist primär für Menschen** (nicht für Maschinen),
|
||||
daher schreiben Sie klar und vermeiden Sie unnötigen Jargon. _Selbst wenn der
|
||||
Code “für sich spricht”_, denken Sie daran, dass klare Erläuterungen später viel
|
||||
Zeit sparen.
|
||||
|
||||
### Checkliste für die Mindest-Dokumentation
|
||||
|
||||
Die folgenden Punkte fassen zusammen, was eine gute Dokumentation mindestens
|
||||
enthalten sollte. Sie können auch als **Qualitäts-Checkliste** dienen, um Ihre
|
||||
Dokumentation zu überprüfen:
|
||||
|
||||
1. **Zielklärung:** Ist der Zweck der Software klar benannt und der
|
||||
wissenschaftliche _Need_ begründet? (Falls nein, ergänzen: _Warum existiert
|
||||
dieses Tool?_)
|
||||
2. **Installation & Voraussetzungen:** Sind alle Schritte, um die Software
|
||||
lauffähig zu machen, dokumentiert (inkl. Dependencies, evtl. mit
|
||||
Installationsbefehlen)? Ist ersichtlich, welche Umgebung nötig ist (OS,
|
||||
Hardware)?
|
||||
3. **Grundlegende Nutzung:** Gibt es eine Anleitung oder Beispiele, wie man die
|
||||
Software verwendet (Eingabe -> Ausgaben)? Ist mindestens ein typischer
|
||||
Workflow beschrieben, idealerweise mit Beispielinput und -output?
|
||||
4. **Optionen & Schnittstellen:** Falls relevant – sind alle wichtigen
|
||||
Funktionen, Befehlsoptionen oder API-Methoden dokumentiert? (Nicht unbedingt
|
||||
jede intern, aber alles, was ein Nutzer aufrufen könnte). Für APIs: Sind
|
||||
Parameter und Rückgaben erläutert?
|
||||
5. **Validierung & Einschränkungen:** Werden Annahmen und Grenzen der Software
|
||||
genannt? Weiß ein*e Nutzer*in, welche Fälle nicht abgedeckt sind oder worauf
|
||||
zu achten ist (z. B. Datenqualität, maximale Größen)? Transparenz hier
|
||||
verhindert Frustration.
|
||||
6. **Hintergrund & Referenzen:** Sind die wichtigsten konzeptionellen
|
||||
Hintergründe oder Referenzen angegeben? (Z. B. theoretische Grundlagen,
|
||||
Algorithmen, Literaturverweise). Das muss kein Essay sein, aber ein paar
|
||||
Sätze + Referenzen schaffen Vertrauen in die wissenschaftliche Fundierung.
|
||||
7. **Kontakt & Weiterführung:** Ist angegeben, wie man Hilfe bekommt oder Fehler
|
||||
melden kann (Issue-Tracker, E-Mail)? Gibt es Hinweise für Beiträge (falls
|
||||
erwünscht) oder zumindest die Information, wer die Autor\*innen sind?
|
||||
8. **Rechtliches & Zitation:** Liegt die Lizenz bei und wird sie genannt? Sind
|
||||
Infos zum Zitieren der Software vorhanden (z. B. “Bitte zitieren Sie DOI
|
||||
XYZ”)? Das stellt sicher, dass die Software nachnutzbar _und_ akademisch
|
||||
kreditiert wird.
|
||||
9. **Aktualität & Version:** Entspricht die Dokumentation der aktuellen
|
||||
Softwareversion? (Check: Versionsnummern, Datumsangaben). Veraltete Doku kann
|
||||
schlimmer sein als keine – planen Sie also ein, die Doku mit jedem Release
|
||||
kurz zu überprüfen.
|
||||
10. **Konsistenz & Stil:** Wird ein einheitlicher Ton und Stil durchgehalten?
|
||||
(z. B. durchgehende Verwendung gleicher Begriffe für Konzepte, Sprache
|
||||
entweder Deutsch oder Englisch einheitlich je nach Zielgruppe). Kleinliche
|
||||
Fehler (Tippfehler, kaputte Links) sind auszumerzen, da sie Nutzer
|
||||
abschrecken.
|
||||
|
||||
Diese Checkliste kann vor einem “Release” der Software durchgegangen werden,
|
||||
ähnlich einem Review-Prozess (vgl. JOSS Review-Kriterien, die viele dieser
|
||||
Punkte abdecken). Sie hilft zu entscheiden, was noch 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.** Beispielsweise interne Code-Refaktorierungsdetails oder
|
||||
historische Anekdoten zur Entwicklung gehören eher ins interne Changelog oder in
|
||||
Blog-Posts, nicht in die Nutzerdokumentation.
|
||||
|
||||
### Positiv- und Negativbeispiele studieren
|
||||
|
||||
Ein guter Weg, die eigene Dokumentation zu verbessern, ist ein Blick auf
|
||||
Projekte mit exzellenter Doku. In der _Journal of Open Source Software (JOSS)_
|
||||
oder _Journal of Open Research Software (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. 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.
|
||||
|
||||
### Prinzipien: FAIR und ENDINGS
|
||||
|
||||
Beachten Sie, dass dieser Anforderungskatalog in Einklang mit den Prinzipien des
|
||||
**Research Software Engineering** und den **ENDINGS-Prinzipien** steht. Gutes
|
||||
Research Software Engineering fördert u.a. _Nachhaltigkeit, Offenheit und
|
||||
Reproduzierbarkeit_ in der Softwareentwicklung. Dementsprechend legt unsere
|
||||
Dokumentations-Checkliste Wert auf Reproduzierbarkeit (Installation, Daten,
|
||||
Beispiele), Offenheit (Lizenz, offene Formate) und Nachhaltigkeit
|
||||
(Versionierung, Langlebigkeit der Doku). 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. 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 ist, 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.). 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). Nutzen Sie auch _Issues_ für
|
||||
Dokumentation: Wenn Nutzer Fragen stellen, überlegen Sie, ob die Antwort in die
|
||||
offizielle Doku übernommen werden sollte. So wächst die Dokumentation organisch
|
||||
entlang der tatsächlichen Bedürfnisse.
|
||||
|
||||
### Zusammenfassung Best Practices
|
||||
|
||||
Zusammenfassend helfen die genannten Best Practices dabei, die Dokumentation
|
||||
**zielgerichtet** zu gestalten: Dokumentiert wird, was dem Verständnis und der
|
||||
Nutzung dient; weggelassen wird, was überflüssig oder selbstverständlich ist.
|
||||
Eine gute Dokumentation _erzählt eine klare Geschichte_ über die Software,
|
||||
anstatt den Leser mit irrelevanten Details zu verlieren. Mit den richtigen
|
||||
Werkzeugen und Prinzipien an der Hand kann selbst unter Zeitdruck eine
|
||||
qualitativ hochwertige Dokumentation entstehen – zur Freude aller, die mit der
|
||||
Forschungssoftware arbeiten möchten.
|
||||
|
||||
## Fazit
|
||||
|
||||
Die hier präsentierten Anforderungen und Empfehlungen bieten einen **Leitfaden
|
||||
für die Dokumentation von Forschungssoftware** in den Digital Humanities. Sie
|
||||
sind darauf ausgerichtet, mit überschaubarem Aufwand maximale
|
||||
**Nachvollziehbarkeit, Langlebigkeit und Wiederverwendbarkeit** zu erreichen.
|
||||
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.
|
||||
|
||||
Wissenschaftlich fundierte Best Practices – von _Ten Simple Rules for
|
||||
Documenting Scientific Software_ bis zu den _ENDINGS-Principles_ – untermauern
|
||||
diesen Katalog. Die Umsetzung dieser Richtlinien wird dazu beitragen, dass
|
||||
Forschungssoftware aus den Geisteswissenschaften nicht nur kurzfristig von ihren
|
||||
Autor\*innen genutzt wird, sondern langfristig von Dritten verstanden, validiert
|
||||
und weiterentwickelt werden kann. So schließt sich der Kreis zwischen guter
|
||||
**Softwareentwicklung** und guter **Wissenschaft**: 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 _Zeiteinsparung bei Nutzern, höherer Zitierbarkeit
|
||||
und größerer Wirkung_ 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: **Gut dokumentierte Forschungscode ist
|
||||
nachhaltige Forschung**.
|
||||
|
||||
### Tabellarische Übersicht der Dokumentations-Bestandteile
|
||||
|
||||
::: {.column-page-right}
|
||||
|
||||
Table: _Empfohlene Dokumentationselemente, Inhalte und Umfang._ 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.
|
||||
|
||||
| **Dokuelement** | **Inhalt/Purpose** | **Format/Ort** | **Umfang** |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------- |
|
||||
| **README (Hauptdoku)** | Zweck der Software; Kurzbeschreibung; Installationsanleitung; einfaches Nutzungsbeispiel; Lizenz- und Kontaktinfo | Markdown im Root des Repos (statisch versioniert) | 1–2 Seiten |
|
||||
| **Eingabe/Ausgabe-Guide** | Beschreibung der erwarteten Inputs (Datenformat, Parameter) und generierten Outputs (Dateien, Berichte) inkl. Beispielen | Teil der README oder separate Datei (z.B. USAGE.md) | 1 Seite (mit Beispielen) |
|
||||
| **Wissenschaftlicher Hintergrund** | Erläuterung der Methode, Theorie, Algorithmen; Verweise auf Literatur | README-Abschnitt "Hintergrund" oder separate Doku (BACKGROUND.md) | 0.5–1 Seite (plus Referenzen) |
|
||||
| **Bekannte Limitationen** | Auflistung von Einschränkungen, Annahmen, bekannten Problemen; ggf. Workarounds | README-Abschnitt "Limitations" oder FAQ.md | 0.5 Seite |
|
||||
| **Beispiel-Workflow (Tutorial)** | Schritt-für-Schritt Anleitung mit einem realistischen Anwendungsfall (ggf. mit Code und Screenshot) | Jupyter Notebook (`.ipynb`) im Repo `examples/` Ordner oder Markdown in docs/ | 1–3 Seiten / entsprechend Zellen |
|
||||
| **API-Referenz** | Technische Dokumentation von Funktionen/Klassen für Entwickler\*innen | Automatisch generiert aus Docstrings (z.B. Sphinx in `docs/` Ordner, HTML/PDF Ausgabe) | Je nach Codegröße (ggf. umfangreich) |
|
||||
| **CONTRIBUTING** | Anleitung für Beitragswillige: Code Style, Workflow, Tests, Kontakt | CONTRIBUTING.md im Repo | 0.5–1 Seite |
|
||||
| **LICENSE** / **CITATION** | Rechtliche Infos (Lizenztext); Zitationsleitfaden (Bevorzugte Zitierweise, DOI) | Jeweils eigene Datei im Repo (Plain Text/Markdown) | Kurz (Standardtext bzw. Referenz) |
|
||||
| **Release-Information** | Versionshinweise, Änderungsprotokoll (Changelog) | CHANGELOG.md oder Releases auf GitHub | fortlaufend pro Version (Stichpunkte) |
|
||||
|
||||
:::
|
||||
|
||||
### Schlusswort
|
||||
|
||||
Mit einer solchen Struktur und Herangehensweise lässt sich auch in einem kleinen
|
||||
Forschungsteam eine professionelle Dokumentation erzielen, die den Prinzipien
|
||||
von Open Science und nachhaltiger Softwareentwicklung gerecht wird. Die
|
||||
investierte Mühe wird durch Zeitgewinn bei Wiederverwendung und Erweiterung der
|
||||
Software mehr als aufgewogen. So wird die Forschungssoftware nicht zum
|
||||
einmaligen “Nebenprodukt”, sondern zu einem robusten, teilbaren Ergebnis
|
||||
wissenschaftlicher Arbeit.
|
||||
69
background/background.bib
Normal file
69
background/background.bib
Normal file
@ -0,0 +1,69 @@
|
||||
@article{wilson2017good,
|
||||
title={Good enough practices in scientific computing},
|
||||
author={Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K},
|
||||
journal={PLoS computational biology},
|
||||
volume={13},
|
||||
number={6},
|
||||
pages={e1005510},
|
||||
year={2017},
|
||||
publisher={Public Library of Science}
|
||||
}
|
||||
|
||||
@article{prlic2012ten,
|
||||
title={Ten simple rules for documenting scientific software},
|
||||
author={Prli{\'c}, Andreas and Procter, James B},
|
||||
journal={PLoS Computational Biology},
|
||||
volume={8},
|
||||
number={12},
|
||||
pages={e1002802},
|
||||
year={2012},
|
||||
publisher={Public Library of Science}
|
||||
}
|
||||
|
||||
@article{smith2016software,
|
||||
title={Software citation principles},
|
||||
author={Smith, Arfon M and Katz, Daniel S and Niemeyer, Kyle E and FORCE11 Software Citation Working Group and others},
|
||||
journal={PeerJ Computer Science},
|
||||
volume={2},
|
||||
pages={e86},
|
||||
year={2016},
|
||||
publisher={PeerJ Inc.}
|
||||
}
|
||||
|
||||
@article{maria2019jupyter,
|
||||
title={Jupyter notebooks—a publishing format for reproducible computational workflows},
|
||||
author={Kluyver, Thomas and Ragan-Kelley, Benjamin and P{\'e}rez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica B and Grout, Jason and Corlay, Sylvain and others},
|
||||
journal={Positioning and Power in Academic Publishing: Players, Agents and Agendas},
|
||||
volume={20},
|
||||
pages={87--90},
|
||||
year={2016},
|
||||
publisher={IOS Press}
|
||||
}
|
||||
|
||||
@misc{endings2020principles,
|
||||
title = {Endings Principles for Digital Longevity},
|
||||
author = {{Endings Project}},
|
||||
year = {2020},
|
||||
url = {https://endings.uvic.ca/principles.html}
|
||||
}
|
||||
|
||||
@article{katz2021open,
|
||||
title={The Journal of Open Source Software (JOSS)},
|
||||
author={Katz, Daniel S and Niemeyer, Kyle E and Smith, Arfon M},
|
||||
journal={PeerJ Computer Science},
|
||||
volume={7},
|
||||
pages={e432},
|
||||
year={2021},
|
||||
publisher={PeerJ Inc.}
|
||||
}
|
||||
|
||||
@article{lamprecht2020towards,
|
||||
title={Towards FAIR principles for research software},
|
||||
author={Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and others},
|
||||
journal={Data Science},
|
||||
volume={3},
|
||||
number={1},
|
||||
pages={37--59},
|
||||
year={2020},
|
||||
publisher={IOS Press}
|
||||
}
|
||||
421
background/springer-humanities-brackets.csl
Normal file
421
background/springer-humanities-brackets.csl
Normal file
@ -0,0 +1,421 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" demote-non-dropping-particle="sort-only" default-locale="en-US">
|
||||
<info>
|
||||
<title>Springer - Humanities (numeric, brackets)</title>
|
||||
<id>http://www.zotero.org/styles/springer-humanities-brackets</id>
|
||||
<link href="http://www.zotero.org/styles/springer-humanities-brackets" rel="self"/>
|
||||
<link href="http://www.zotero.org/styles/springer-humanities-author-date" rel="template"/>
|
||||
<link href="www.springer.com/cda/content/document/cda_downloaddocument/Key_Style_Points_Aug2012.pdf" rel="documentation"/>
|
||||
<author>
|
||||
<name>Sebastian Karcher</name>
|
||||
</author>
|
||||
<contributor>
|
||||
<name>Julian Onions</name>
|
||||
<email>julian.onions@gmail.com</email>
|
||||
</contributor>
|
||||
<contributor>
|
||||
<name>Richard Karnesky</name>
|
||||
<email>karnesky+zotero@gmail.com</email>
|
||||
<uri>http://arc.nucapt.northwestern.edu/Richard_Karnesky</uri>
|
||||
</contributor>
|
||||
<contributor>
|
||||
<name>Charles Parnot</name>
|
||||
<email>charles.parnot@gmail.com</email>
|
||||
<uri>http://twitter.com/cparnot</uri>
|
||||
</contributor>
|
||||
<category citation-format="numeric"/>
|
||||
<category field="generic-base"/>
|
||||
<category field="humanities"/>
|
||||
<summary>Style for Springer's humanities journals - the journals do look slightly different from each other, but this should work quite closely</summary>
|
||||
<updated>2019-10-01T00:21:45+00:00</updated>
|
||||
<rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
|
||||
</info>
|
||||
<locale>
|
||||
<terms>
|
||||
<term name="container-author" form="verb">by</term>
|
||||
</terms>
|
||||
</locale>
|
||||
<macro name="secondary-contributors">
|
||||
<choose>
|
||||
<if type="chapter paper-conference" match="none">
|
||||
<group delimiter=". ">
|
||||
<choose>
|
||||
<if variable="author">
|
||||
<names variable="editor">
|
||||
<label form="verb" text-case="capitalize-first" suffix=" " plural="never"/>
|
||||
<name and="text" delimiter=", "/>
|
||||
</names>
|
||||
</if>
|
||||
</choose>
|
||||
<choose>
|
||||
<if variable="author editor" match="any">
|
||||
<names variable="translator">
|
||||
<label form="verb" text-case="capitalize-first" suffix=" " plural="never"/>
|
||||
<name and="text" delimiter=", "/>
|
||||
</names>
|
||||
</if>
|
||||
</choose>
|
||||
</group>
|
||||
</if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="container-contributors">
|
||||
<choose>
|
||||
<if type="chapter paper-conference" match="any">
|
||||
<group prefix=", " delimiter=", ">
|
||||
<choose>
|
||||
<if variable="author">
|
||||
<names variable="container-author editor" delimiter=", ">
|
||||
<label form="short" suffix=" " plural="never"/>
|
||||
<name and="text" delimiter=", " initialize="false" initialize-with=". "/>
|
||||
</names>
|
||||
</if>
|
||||
</choose>
|
||||
<choose>
|
||||
<if variable="author editor" match="any">
|
||||
<names variable="translator">
|
||||
<label form="short" plural="never" suffix=" "/>
|
||||
<name and="text" delimiter=", "/>
|
||||
</names>
|
||||
</if>
|
||||
</choose>
|
||||
</group>
|
||||
</if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="recipient">
|
||||
<choose>
|
||||
<if type="personal_communication">
|
||||
<choose>
|
||||
<if variable="genre">
|
||||
<text variable="genre" text-case="capitalize-first"/>
|
||||
</if>
|
||||
<else>
|
||||
<text term="letter" text-case="capitalize-first"/>
|
||||
</else>
|
||||
</choose>
|
||||
</if>
|
||||
</choose>
|
||||
<names variable="recipient" delimiter=", ">
|
||||
<label form="verb" prefix=" " suffix=" "/>
|
||||
<name and="text" delimiter=", "/>
|
||||
</names>
|
||||
</macro>
|
||||
<macro name="contributors">
|
||||
<names variable="author">
|
||||
<name and="text" name-as-sort-order="first" sort-separator=", " delimiter=", " delimiter-precedes-last="always"/>
|
||||
<label form="short" plural="never" prefix=", "/>
|
||||
<substitute>
|
||||
<names variable="editor"/>
|
||||
<names variable="translator"/>
|
||||
<text macro="title"/>
|
||||
</substitute>
|
||||
</names>
|
||||
<text macro="recipient"/>
|
||||
</macro>
|
||||
<macro name="interviewer">
|
||||
<names variable="interviewer" delimiter=", ">
|
||||
<label form="verb" prefix=" " text-case="capitalize-first" suffix=" "/>
|
||||
<name and="text" delimiter=", "/>
|
||||
</names>
|
||||
</macro>
|
||||
<macro name="archive">
|
||||
<group delimiter=". ">
|
||||
<text variable="archive_location" text-case="capitalize-first"/>
|
||||
<text variable="archive"/>
|
||||
<text variable="archive-place"/>
|
||||
</group>
|
||||
</macro>
|
||||
<macro name="access">
|
||||
<group delimiter=". ">
|
||||
<choose>
|
||||
<if type="graphic report" match="any">
|
||||
<text macro="archive"/>
|
||||
</if>
|
||||
<else-if type="article-magazine article-newspaper bill book chapter graphic legal_case legislation motion_picture paper-conference report song thesis" match="none">
|
||||
<text macro="archive"/>
|
||||
</else-if>
|
||||
</choose>
|
||||
<text variable="DOI" prefix="https://doi.org/"/>
|
||||
<choose>
|
||||
<if variable="DOI issued" match="none">
|
||||
<choose>
|
||||
<if variable="URL accessed" match="all">
|
||||
<choose>
|
||||
<if type="legal_case" match="none">
|
||||
<text variable="URL"/>
|
||||
</if>
|
||||
</choose>
|
||||
<group delimiter=" ">
|
||||
<text term="accessed" text-case="capitalize-first"/>
|
||||
<date variable="accessed" delimiter=" ">
|
||||
<date-part name="month"/>
|
||||
<date-part name="day"/>
|
||||
</date>
|
||||
</group>
|
||||
</if>
|
||||
</choose>
|
||||
</if>
|
||||
<else-if type="webpage">
|
||||
<date variable="issued" delimiter=" ">
|
||||
<date-part name="month"/>
|
||||
<date-part name="day"/>
|
||||
</date>
|
||||
</else-if>
|
||||
</choose>
|
||||
</group>
|
||||
</macro>
|
||||
<macro name="title">
|
||||
<choose>
|
||||
<if variable="title" match="none">
|
||||
<choose>
|
||||
<if type="personal_communication" match="none">
|
||||
<text variable="genre" text-case="capitalize-first"/>
|
||||
</if>
|
||||
</choose>
|
||||
</if>
|
||||
<else-if type="bill book graphic legal_case legislation motion_picture report song" match="any">
|
||||
<text variable="title" font-style="italic"/>
|
||||
</else-if>
|
||||
<else>
|
||||
<text variable="title"/>
|
||||
</else>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="edition">
|
||||
<choose>
|
||||
<if type="bill book graphic legal_case legislation motion_picture report song" match="any">
|
||||
<choose>
|
||||
<if is-numeric="edition">
|
||||
<group delimiter=" " prefix=". ">
|
||||
<number variable="edition" form="ordinal"/>
|
||||
<text term="edition" form="short"/>
|
||||
</group>
|
||||
</if>
|
||||
<else>
|
||||
<text variable="edition" prefix=". "/>
|
||||
</else>
|
||||
</choose>
|
||||
</if>
|
||||
<else-if type="chapter paper-conference" match="any">
|
||||
<choose>
|
||||
<if is-numeric="edition">
|
||||
<group delimiter=" " prefix=", ">
|
||||
<number variable="edition" form="ordinal"/>
|
||||
<text term="edition" form="short"/>
|
||||
</group>
|
||||
</if>
|
||||
<else>
|
||||
<text variable="edition" prefix=", "/>
|
||||
</else>
|
||||
</choose>
|
||||
</else-if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="locators">
|
||||
<choose>
|
||||
<if type="article-journal">
|
||||
<text variable="volume" prefix=" "/>
|
||||
</if>
|
||||
<else-if type="legal_case">
|
||||
<text variable="volume" prefix=", "/>
|
||||
<text variable="container-title" prefix=" "/>
|
||||
<text variable="page" prefix=" "/>
|
||||
</else-if>
|
||||
<else-if type="bill book graphic legal_case legislation motion_picture report song" match="any">
|
||||
<group prefix=". " delimiter=". ">
|
||||
<group>
|
||||
<text term="volume" form="short" text-case="capitalize-first" suffix=" "/>
|
||||
<number variable="volume" form="numeric"/>
|
||||
</group>
|
||||
<group>
|
||||
<number variable="number-of-volumes" form="numeric"/>
|
||||
<text term="volume" form="short" prefix=" " plural="true"/>
|
||||
</group>
|
||||
</group>
|
||||
</else-if>
|
||||
<else-if type="chapter paper-conference" match="any">
|
||||
<choose>
|
||||
<if variable="page" match="none">
|
||||
<group prefix=". ">
|
||||
<text term="volume" form="short" text-case="capitalize-first" suffix=" "/>
|
||||
<number variable="volume" form="numeric"/>
|
||||
</group>
|
||||
</if>
|
||||
</choose>
|
||||
</else-if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="locators-chapter">
|
||||
<choose>
|
||||
<if type="chapter paper-conference" match="any">
|
||||
<choose>
|
||||
<if variable="page">
|
||||
<group prefix=", ">
|
||||
<text variable="volume" suffix=":"/>
|
||||
<text variable="page"/>
|
||||
</group>
|
||||
</if>
|
||||
</choose>
|
||||
</if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="locators-article">
|
||||
<choose>
|
||||
<if type="article-newspaper">
|
||||
<group prefix=", " delimiter=", ">
|
||||
<group delimiter=" ">
|
||||
<text variable="edition"/>
|
||||
<text term="edition"/>
|
||||
</group>
|
||||
<group>
|
||||
<text term="section" form="short" suffix=" "/>
|
||||
<text variable="section"/>
|
||||
</group>
|
||||
</group>
|
||||
</if>
|
||||
<else-if type="article-journal">
|
||||
<text variable="page" prefix=": "/>
|
||||
</else-if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="container-prefix">
|
||||
<text term="in" text-case="capitalize-first"/>
|
||||
</macro>
|
||||
<macro name="container-title">
|
||||
<choose>
|
||||
<if type="chapter paper-conference" match="any">
|
||||
<text macro="container-prefix" suffix=" "/>
|
||||
</if>
|
||||
</choose>
|
||||
<choose>
|
||||
<if type="legal_case" match="none">
|
||||
<text variable="container-title" font-style="italic"/>
|
||||
</if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="publisher">
|
||||
<group delimiter=": ">
|
||||
<text variable="publisher-place"/>
|
||||
<text variable="publisher"/>
|
||||
</group>
|
||||
</macro>
|
||||
<macro name="date">
|
||||
<choose>
|
||||
<if variable="issued">
|
||||
<date variable="issued">
|
||||
<date-part name="year"/>
|
||||
</date>
|
||||
</if>
|
||||
<else-if variable="accessed">
|
||||
<date variable="accessed">
|
||||
<date-part name="year"/>
|
||||
</date>
|
||||
</else-if>
|
||||
</choose>
|
||||
</macro>
|
||||
<macro name="day-month">
|
||||
<date variable="issued">
|
||||
<date-part name="month"/>
|
||||
<date-part name="day" prefix=" "/>
|
||||
</date>
|
||||
</macro>
|
||||
<macro name="collection-title">
|
||||
<text variable="collection-title" text-case="title"/>
|
||||
<text variable="collection-number" prefix=" "/>
|
||||
</macro>
|
||||
<macro name="event">
|
||||
<group>
|
||||
<text term="presented at" suffix=" "/>
|
||||
<text variable="event"/>
|
||||
</group>
|
||||
</macro>
|
||||
<macro name="description">
|
||||
<choose>
|
||||
<if type="interview">
|
||||
<group delimiter=". ">
|
||||
<text macro="interviewer"/>
|
||||
<text variable="medium" text-case="capitalize-first"/>
|
||||
</group>
|
||||
</if>
|
||||
<else>
|
||||
<text variable="medium" text-case="capitalize-first" prefix=". "/>
|
||||
</else>
|
||||
</choose>
|
||||
<choose>
|
||||
<if variable="title" match="none"/>
|
||||
<else-if type="thesis"/>
|
||||
<else>
|
||||
<group delimiter=" " prefix=". ">
|
||||
<text variable="genre" text-case="capitalize-first"/>
|
||||
<choose>
|
||||
<if type="report">
|
||||
<text variable="number"/>
|
||||
</if>
|
||||
</choose>
|
||||
</group>
|
||||
</else>
|
||||
</choose>
|
||||
<!--This is for computer programs only. Localization new to 1.0.1, so may be missing in many locales-->
|
||||
<group delimiter=" " prefix=" (" suffix=")">
|
||||
<text term="version"/>
|
||||
<text variable="version"/>
|
||||
</group>
|
||||
</macro>
|
||||
<macro name="issue">
|
||||
<choose>
|
||||
<if type="legal_case">
|
||||
<text variable="authority" prefix=". "/>
|
||||
</if>
|
||||
<else-if type="speech">
|
||||
<group prefix=" " delimiter=", ">
|
||||
<text macro="event"/>
|
||||
<text macro="day-month"/>
|
||||
<text variable="event-place"/>
|
||||
</group>
|
||||
</else-if>
|
||||
<else-if type="article-newspaper article-magazine" match="any">
|
||||
<text macro="day-month" prefix=", "/>
|
||||
</else-if>
|
||||
<else>
|
||||
<group prefix=". " delimiter=", ">
|
||||
<choose>
|
||||
<if type="thesis">
|
||||
<text variable="genre" text-case="capitalize-first"/>
|
||||
</if>
|
||||
</choose>
|
||||
<text macro="publisher"/>
|
||||
</group>
|
||||
</else>
|
||||
</choose>
|
||||
</macro>
|
||||
<citation collapse="citation-number">
|
||||
<sort>
|
||||
<key variable="citation-number"/>
|
||||
</sort>
|
||||
<layout prefix="[" suffix="]" delimiter=", ">
|
||||
<text variable="citation-number"/>
|
||||
</layout>
|
||||
</citation>
|
||||
<bibliography second-field-align="flush" et-al-min="11" et-al-use-first="7" entry-spacing="0">
|
||||
<layout suffix=".">
|
||||
<text variable="citation-number" suffix=". "/>
|
||||
<group delimiter=". ">
|
||||
<text macro="contributors"/>
|
||||
<text macro="date"/>
|
||||
<text macro="title"/>
|
||||
</group>
|
||||
<text macro="description"/>
|
||||
<text macro="secondary-contributors" prefix=". "/>
|
||||
<text macro="container-title" prefix=". "/>
|
||||
<text macro="container-contributors"/>
|
||||
<text macro="edition"/>
|
||||
<text macro="locators-chapter"/>
|
||||
<text macro="locators"/>
|
||||
<text macro="collection-title" prefix=". "/>
|
||||
<text macro="issue"/>
|
||||
<text macro="locators-article"/>
|
||||
<text macro="access" prefix=". "/>
|
||||
</layout>
|
||||
</bibliography>
|
||||
</style>
|
||||
119
background/themes/nfdi.scss
Normal file
119
background/themes/nfdi.scss
Normal file
@ -0,0 +1,119 @@
|
||||
/*-- scss:defaults --*/
|
||||
// --primary-color: light-dark(#006890,#004f6e);
|
||||
|
||||
|
||||
$blue: #004f6e !default;
|
||||
$blue-light: #006890 !default;
|
||||
// $indigo: #6610f2 !default;
|
||||
$purple: #7e3f73 !default;
|
||||
// $pink: #d63384 !default;
|
||||
$red: #c44814 !default;
|
||||
// $orange: #fd7e14 !default;
|
||||
$yellow: #deae00 !default;
|
||||
$green: #7ba01e !default;
|
||||
// $teal: #20c997 !default;
|
||||
$cyan: #008ac0 !default;
|
||||
$gray: #9d9d9d !default;
|
||||
|
||||
$white: #fff !default;
|
||||
$gray-100: tint-color($gray, 80%) !default;
|
||||
$gray-200: tint-color($gray, 60%) !default;
|
||||
$gray-300: tint-color($gray, 40%) !default;
|
||||
$gray-400: tint-color($gray, 20%) !default;
|
||||
$gray-500: $gray !default;
|
||||
$gray-600: shade-color($gray, 20%) !default;
|
||||
$gray-700: shade-color($gray, 40%) !default;
|
||||
$gray-800: shade-color($gray, 60%) !default;
|
||||
$gray-900: shade-color($gray, 80%) !default;
|
||||
$black: #000 !default;
|
||||
|
||||
$primary: $blue !default;
|
||||
$secondary: $blue-light !default;
|
||||
$accent: $yellow !default;
|
||||
$success: $green !default;
|
||||
$info: $cyan !default;
|
||||
$warning: $yellow !default;
|
||||
$danger: $red !default;
|
||||
$light: $gray-100 !default;
|
||||
$dark: $gray-900 !default;
|
||||
|
||||
$min-contrast-ratio: 2.6 !default;
|
||||
|
||||
$link-color: $secondary !default;
|
||||
// Options
|
||||
|
||||
$enable-rounded: true !default;
|
||||
|
||||
// Body
|
||||
|
||||
$body-color: $gray-800 !default;
|
||||
|
||||
// Fonts
|
||||
|
||||
// stylelint-disable-next-line value-keyword-case
|
||||
//$font-family-sans-serif: "Source Sans Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;
|
||||
$headings-font-weight: 400 !default;
|
||||
|
||||
// Navbar
|
||||
|
||||
$navbar-dark-hover-color: rgba($white, 1) !default;
|
||||
$navbar-light-hover-color: rgba($black, .9) !default;
|
||||
|
||||
// Alerts
|
||||
|
||||
$alert-border-width: 0 !default;
|
||||
|
||||
// Progress bars
|
||||
|
||||
$progress-height: .5rem !default;
|
||||
|
||||
|
||||
/*-- scss:rules --*/
|
||||
|
||||
|
||||
// Variables
|
||||
|
||||
// $web-font-path: "https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@300;400;700&display=swap" !default;
|
||||
// @if $web-font-path {
|
||||
// @import url($web-font-path);
|
||||
// }
|
||||
|
||||
// Typography
|
||||
|
||||
body {
|
||||
-webkit-font-smoothing: antialiased;
|
||||
}
|
||||
|
||||
// Indicators
|
||||
|
||||
.badge {
|
||||
&.bg-light {
|
||||
color: $dark;
|
||||
}
|
||||
}
|
||||
|
||||
// Progress bars
|
||||
|
||||
.progress {
|
||||
@include box-shadow(none);
|
||||
|
||||
.progress-bar {
|
||||
font-size: 8px;
|
||||
line-height: 8px;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
color: $primary;
|
||||
}
|
||||
|
||||
|
||||
strong {
|
||||
text-shadow: 0px 0px 1px $secondary;
|
||||
}
|
||||
|
||||
em {
|
||||
text-shadow: 0px 0px 1px $secondary;
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user