diff --git a/example-project/README.md b/example-project/README.md index 328c654..ec4b4ad 100644 --- a/example-project/README.md +++ b/example-project/README.md @@ -1,47 +1,161 @@ -# Projektname +--- +title: "" +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 -wissenschaftliche Problem sie löst. +Auf Wunsch Beschreibung noch einmal wiederholen -## 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` -- **Keine ausführliche Erklärung** von Standard-Tools (z.B. Python - installieren), sondern verlinken auf offizielle Seiten +- Verweise ggf. auf ausführliche [INSTALL.md](INSTALL.md) -## 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 - (`USAGE.md`) verweisen +> [!warning] +> +> **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial (Datei +> [USAGE.md](USAGE.md) oder Verzeichnis [examples/](examples/)) verweisen -## Wissenschaftlicher Hintergrund - -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 +### 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.