| title | description | lang | date | authors | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Good™ Documentation | Dieses Repository enthält eine Beispielstruktur, nach welchen Regeln und in welcher Ausführlichkeit sinnvoll dokumentiert werden sollte. | de | 2025-06-03 |
|
Ziel / Zweck
Dokumentation ist hilfreich, dennoch fällt sie meist anderen Sachzwängen zum Opfer. Dieses Repository bietet diverse Markdown-Dateien als ausfüllbare Vorlage, damit man sich auf das wesentliche konzentrieren kann bzw. wichtige Dinge für etwaige Nachfolger*innen nicht vergisst.
Nutzung
Wir haben GitLab-Templates, die man benutzen kann, wenn man ein Projekt startet. Falls bereits Code oder ein Repository besteht, ist es am Besten, wenn man dennoch im GitLab ein neues Projekt mit diesem Template erstellt und anschließend die existierenden Dateien herüberkopiert.
- Neues Projekt erstellen
- Aus Template
- Gruppe wählen
- Template auswählen & erstellen
Code-Project
Das Code-Project-Template ist für Repositories gedacht, die irgendeine Art von Verarbeitung haben, bei der primär Daten analysiert, weiterverarbeitet oder ausgewertet werden ODER es sich um ein Applikationsprojekt im klassischen Sinne handelt.
Ziel ist hier die Entwicklung und langfristig die Installation, Veröffentlichung,Nutzung und Wartung der Software.
Zur genauer Struktur und Handhabung sei auf die README.md dort verwiesen.
Daten-Project
Analog zum Code-Project ist das Daten-Project-Template für Repositories gedacht, die irgendeine Art von Daten als Output haben. Hierbei geht es um die reine Vorverarbeitung der Daten und nicht um Analyse. Typischerweise liegen hier z.b. Roh-Daten (Bilder, etc.) vor und der Output ist ein Maschinenlesbares Format (z.b. JSON des Textes mit Annotationen).
Ziel ist hier die Dokumentation und die Reproduzierbarkeit von
Quelle -> Datensatz.
Zur genauer Struktur und Handhabung sei auf die README.md dort verwiesen.
Wissenschaftlicher Hintergrund
Dieses gesamte Repository wurde erstellt um Forschenden eine fundierte, praktische Hilfe zu geben, um ihre Projekte nach guten Standards zu dokumentieren. Insbesondere hervorzuheben sind hier die Endings-Principles for Digital Longevity, FAIR-Principles und den Ten simple rules for documenting scientific software.
Für eine Ausführliche auseinandersetzung mit dieser Thematik siehe BACKGROUND.md
Bekannte Einschränkungen
Dieses Repository sollte nicht als der einzig richtige Weg angesehen werden, sondern ist eher ein Aufschlag, Erkenntnisse in der eigenen Arbeit auch praktisch umzusetzen. Jede hier aufgestellte Regel und Empfehlung kann und sollte - je nach Umständen - auch gebrochen werden.
Lizenz & Zitation
Folgt...