8.5 KiB
title, description, lang, date, authors
| title | description | lang | date | authors | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| <Projektname> | Kurze Beschreibung (2-3 Sätze), was die Software macht und welches wissenschaftliche Problem sie löst. | de | 2025-05-14 |
|
Auf Wunsch Beschreibung noch einmal wiederholen
Ü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.“)
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
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).
Warning
Nicht zu komplexe Beispiele, dafür ggf. auf ausführliches Tutorial (Datei USAGE.md oder Verzeichnis examples/) verweisen
Bekannte Einschränkungen
Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu vermeiden.
Warning
Keine ausschweifenden technischen Details, sondern praktische Hinweise.
Struktur
Ü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.mdim 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)
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).
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ß eine Nutzerin, 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.