data-project-template/README.md

---
title: "<Projektname>"
description: |
  Kurze Beschreibung (2-3 Sätze), was für Daten hier liegen.
lang: de
date: 2025-01-01
status: "initial planning..."
authors:
  - name: Your Name
    affiliation:
      - name: Your Institution
        url: Institutions homepage
    email: your@email.here
    orcid: 0000-0000-0000-0000
    roles: # CRediT-Roles - see https://credit.niso.org/
      - Conceptualization
      - Supervision
      - Validation
  # ... weitere Autor*innen
---

Auf Wunsch Beschreibung noch einmal wiederholen

## Über dieses Repository

### Ziel / Zweck

Kurz das Ziel oder den Bedarf für diese Daten erläutern.  
(Beispiel: „Dieser Datensatz besteht aus … und eignet sich als Benchmark um die
Performance der Named Entity Recognition zu testen.“)

Sind die Daten Final? Werden sie noch gesammelt? Wann wird mit Abschluss
gerechnet?

### Reproduktion

Kurz und präzise beschreiben, wie aus den Quelldaten der aktuelle Datensatz
erstellt wurde - also wie beiliegender Code und Scripte ausgeführt werden
müssen.

- Verweise ggf. auf ausführliche [INSTALL.md](INSTALL.md)

> [!warning]
>
> **Keine ausführliche Erklärung** von Standard-Tools (z.B. Python
> installieren), sondern verlinken auf offizielle Seiten

### Nutzung / Bekannte Einschränkungen

- Wann sollte ich den Datensatz nutzen?
- Wann sollte ich den Datensatz **nicht** nutzen?
- Welche **Biases** gibt es in den Daten?

### Struktur

```plain
Übersicht der Struktur z.b. generiert mittels
`tree -L2` oder `tree -L2 -d`
und anschließend überarbeitet
```

Ein Beispiel könnte sein:

```plain
.
├── raw/            # raw data
├── src/            # code to process raw/ into data/
├── data/           # processed data
├── CHANGELOG.md
├── CITATION.md     # how to cite
├── CONTRIBUTING.md
├── INSTALL.md      # instructions to reproduce
└── README.md       # this file
```

- Kurze Beschreibung - entweder direkt im Tree oder hier in Prosa
- Ziel: Überblick über "Wo finde ich was". Wo ist Code? Wo ist ...?

> [!warning]
>
> **Keine Details**, die über 1 Satz pro Element hinaus gehen. Bei detailliertem
> Bedarf `README.md` im jeweiligen Verzeichnis.

## Meta-Informationen

### Verantwortlichkeiten

- Wer ist letztendlich verantwortlich für den Inhalt?
- Wer genehmigt/weist Inhalte ab?

### Wissenschaftlicher Hintergrund

Kurze Erklärung der wissenschaftlichen Grundlage (Methode, theoretischer Ansatz)
und Referenzen auf Publikationen oder Quellen.

> [!warning]
>
> **Keine ausführliche Theorie**, diese gehört in Paper oder eigene Datei
> ([BACKGROUND.md](BACKGROUND.md))

### Lizenz & Zitation

Kurz auf Lizenz verweisen (z.B. „siehe LICENSE“) und erklären, wie das Projekt
zu zitieren ist (z.B. DOI oder Verweis auf [CITATION.md](CITATION.md)).

---

## Empfohlene Dokumentations-Dateien

| **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                            |
| **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      |
| **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) |

## Checklist

Es ist eine gute Idee die sich ändernden Punkte in ein Release-Template zu
kopieren.

- [ ] **Installation & Reproduzierbarkeit:** Sind alle Schritte, um die Daten
      aus den Quelldaten erneut zu erstellen, dokumentiert (inkl. Dependencies,
      evtl. mit Installationsbefehlen)? Ist ersichtlich, welche Umgebung nötig
      ist (OS, Hardware)?
- [ ] **Grundlegende Nutzung:** Gibt es eine Anleitung oder Beispiele, wie man
      die Daten verwendet (Daten -> Variablen in einer Programmiersprache)? Ist
      mindestens ein typischer Workflow beschrieben, idealerweise mit
      Beispielinput und -output?
- [ ] **Hintergrund & Referenzen:** Sind die wichtigsten Hintergründe oder
      Referenzen über den Ursprung der Daten angegeben? Das muss kein Essay
      sein, aber ein paar Sätze + Referenzen schaffen Vertrauen in die
      wissenschaftliche Fundierung.
- [ ] **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?
- [ ] **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.
- [ ] **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.
- [ ] **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.