example-project/CITATION.md

@@ -6,14 +6,4 @@ 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,7 +1,3 @@
----
-date: 2025-05-14 # when was this touched last?
----
-
 # Installation
 
 Ausführliche Schritt-für-Schritt Anleitung zur Installation.

example-project/README.md

@@ -1,161 +1,47 @@
----
+# 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
----
 
-Auf Wunsch Beschreibung noch einmal wiederholen
+Kurze Beschreibung (2-3 Sätze), was die Software macht und welches
+wissenschaftliche Problem sie löst.
 
-## Über dieses Repository
+## Ziel / Zweck
-
-### Ziel / Zweck
 
 Kurz das Ziel oder den Bedarf der Software erläutern.  
 (Beispiel: „Diese Software analysiert historische Textdaten, um Netzwerke
 sozialer Interaktionen zu rekonstruieren.“)
 
-Ist die Software noch in Entwicklung? Abgeschlossen? Abgebrochen?
+## Installation
-
-### Installation
 
 Kurz und präzise beschreiben, wie die Software installiert wird (max. 3-5
 Schritte).
 
-- Verweise ggf. auf ausführliche [INSTALL.md](INSTALL.md)
+- Verweise ggf. auf ausführliche `INSTALL.md`
+- **Keine ausführliche Erklärung** von Standard-Tools (z.B. Python
+  installieren), sondern verlinken auf offizielle Seiten
 
-> [!warning]
+## Nutzung
->
-> **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).
 
-> [!warning]
+- **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial
->
+  (`USAGE.md`) verweisen
-> **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial (Datei
-> [USAGE.md](USAGE.md) oder Verzeichnis [examples/](examples/)) verweisen
 
-### Bekannte Einschränkungen
+## Wissenschaftlicher Hintergrund
-
-Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu
-vermeiden.
-
-> [!warning]
->
-> **Keine** ausschweifenden technischen Details, sondern praktische Hinweise.
-
-### 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`)
-> **Keine ausführliche Theorie**, diese gehört in Paper oder eigene Datei
-> ([BACKGROUND.md](BACKGROUND.md))
 
-### Lizenz & Zitation
+## Bekannte Einschränkungen
+
+Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu
+vermeiden.
+
+- **Keine** ausschweifenden technischen Details, sondern praktische Hinweise.
+
+## 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)).
+zu zitieren ist (z.B. DOI oder Verweis auf `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,8 +1,4 @@
----
+# 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.