added yaml header where appropiate, added bibtex-example to CITATION

example-project/CITATION.md

@@ -6,4 +6,14 @@ Nenne hier die bevorzugte Zitierweise für Publikationen oder DOI:
 Nachname, Vorname. (Jahr). Projektname (Version X.Y.Z). DOI oder URL.
 ```
 
+```bibtex
+@software{bibtex-key,
+  author = {{}},
+  title = {Projektname},
+  url = {Projekthomepage},
+  version = {version},
+  date = {datum versions-release},
+}
+```
+
 - **Keine langen Beschreibungen**, nur den Zitierhinweis.

example-project/INSTALL.md

@@ -1,3 +1,7 @@
+---
+date: 2025-05-14 # when was this touched last?
+---
+
 # Installation
 
 Ausführliche Schritt-für-Schritt Anleitung zur Installation.

example-project/README.md

@@ -1,47 +1,161 @@
-# Projektname
+---
+title: "<Projektname>"
+description: |
+  Kurze Beschreibung (2-3 Sätze), was die Software macht und welches wissenschaftliche Problem sie löst.
+lang: de
+date: 2025-05-14
+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
+---
 
-Kurze Beschreibung (2-3 Sätze), was die Software macht und welches
+Auf Wunsch Beschreibung noch einmal wiederholen
-wissenschaftliche Problem sie löst.
 
-## Ziel / Zweck
+## Über dieses Repository
+
+### Ziel / Zweck
 
 Kurz das Ziel oder den Bedarf der Software erläutern.  
 (Beispiel: „Diese Software analysiert historische Textdaten, um Netzwerke
 sozialer Interaktionen zu rekonstruieren.“)
 
-## Installation
+Ist die Software noch in Entwicklung? Abgeschlossen? Abgebrochen?
+
+### Installation
 
 Kurz und präzise beschreiben, wie die Software installiert wird (max. 3-5
 Schritte).
 
-- Verweise ggf. auf ausführliche `INSTALL.md`
+- Verweise ggf. auf ausführliche [INSTALL.md](INSTALL.md)
-- **Keine ausführliche Erklärung** von Standard-Tools (z.B. Python
-  installieren), sondern verlinken auf offizielle Seiten
 
-## Nutzung
+> [!warning]
+>
+> **Keine ausführliche Erklärung** von Standard-Tools (z.B. Python
+> installieren), sondern verlinken auf offizielle Seiten
+
+### Nutzung
 
 Minimalbeispiel, wie die Software genutzt wird (kurzer Codeblock oder
 Kommandozeilenaufruf mit typischem Input und Output).
 
-- **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial
+> [!warning]
-  (`USAGE.md`) verweisen
+>
+> **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial (Datei
+> [USAGE.md](USAGE.md) oder Verzeichnis [examples/](examples/)) verweisen
 
-## Wissenschaftlicher Hintergrund
+### Bekannte Einschränkungen
-
-Kurze Erklärung der wissenschaftlichen Grundlage (Methode, theoretischer Ansatz)
-und Referenzen auf Publikationen oder Quellen.
-
-- **Keine ausführliche Theorie**, diese gehört in Paper oder eigene Datei
-  (`BACKGROUND.md`)
-
-## Bekannte Einschränkungen
 
 Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu
 vermeiden.
 
-- **Keine** ausschweifenden technischen Details, sondern praktische Hinweise.
+> [!warning]
+>
+> **Keine** ausschweifenden technischen Details, sondern praktische Hinweise.
 
-## Lizenz & Zitation
+### Struktur
+
+```plain
+Übersicht der Struktur z.b. generiert mittels
+`tree -L2` oder `tree -L2 -d`
+und anschließend überarbeitet
+```
+
+- Kurze Beschreibung - entweder direkt im Tree oder hier in Prosa
+- Ziel: Überblick über "Wo finde ich was". Wo ist Doku? 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`).
+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                            |
+| **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) |
+
+## Checklist
+
+Es ist eine gute Idee die sich ändernden Punkte in ein Release-Template zu
+kopieren.
+
+- [ ] **Zielklärung:** Ist der Zweck der Software klar benannt und der
+      wissenschaftliche _Need_ begründet? (Falls nein, ergänzen: _Warum
+      existiert dieses Tool?_)
+- [ ] **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)?
+- [ ] **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?
+- [ ] **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?
+- [ ] **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.
+- [ ] **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.
+- [ ] **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.

example-project/USAGE.md

@@ -1,4 +1,8 @@
-# Nutzung der Software
+---
+title: "Nutzung der Software"
+date: 2025-05-14 # zuletzt angepasst
+version: v1.0 # Auf welche Version bezieht sich dies?
+---
 
 Ausführliche Beschreibung typischer Workflows oder Beispielanwendungen.