mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-08 09:59:06 +00:00
Updated README.md for example-project according to meeting.
This commit is contained in:
Nicole Dresselhaus
parent
bb661ce672
commit
1d5dc729fd
@ -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.
|
Kurz das Ziel oder den Bedarf der Software erläutern.
|
||||||
(Beispiel: „Diese Software analysiert historische Textdaten, um Netzwerke
|
(Beispiel: „Diese Software analysiert historische Textdaten, um Netzwerke
|
||||||
sozialer Interaktionen zu rekonstruieren.“)
|
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
|
Kurz und präzise beschreiben, wie die Software installiert wird (max. 3-5
|
||||||
Schritte).
|
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
|
Minimalbeispiel, wie die Software genutzt wird (kurzer Codeblock oder
|
||||||
Kommandozeilenaufruf mit typischem Input und Output).
|
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
|
Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu
|
||||||
vermeiden.
|
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
|
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.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user