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