mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-08 01:49:07 +00:00
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
---
|
||
title: Good™ Documentation
|
||
description: |
|
||
Dieses Repository enthält eine Beispielstruktur, nach welchen Regeln und in welcher Ausführlichkeit sinnvoll dokumentiert werden sollte.
|
||
lang: de
|
||
date: 2025-06-03
|
||
authors:
|
||
- name: Nicole Dresselhaus
|
||
affiliation:
|
||
- name: Humboldt-Universität zu Berlin
|
||
url: https://hu-berlin.de
|
||
email: nicole.dresselhaus@hu-berlin.de
|
||
correspondence: true
|
||
orcid: 0009-0008-8850-3679
|
||
roles:
|
||
- Conceptualization
|
||
- "Writing – first draft"
|
||
- "Writing – review & editing"
|
||
- name: Till Grallert
|
||
affiliation:
|
||
- name: Humboldt-Universität zu Berlin
|
||
url: https://hu-berlin.de
|
||
email: till.grallert@hu-berlin.de
|
||
roles:
|
||
- Supervision
|
||
- Validation
|
||
---
|
||
|
||
## 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.
|
||
|
||
1. Neues Projekt erstellen
|
||
|
||
2. Aus Template
|
||
|
||
3. Gruppe wählen
|
||
|
||
4. Template auswählen & erstellen
|
||
|
||
|
||
### Code-Project
|
||
|
||
Das
|
||
[Code-Project-Template](https://scm.cms.hu-berlin.de/methodenlabor/templates/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](https://scm.cms.hu-berlin.de/methodenlabor/templates/data-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](https://endings.uvic.ca/principles.html),
|
||
[FAIR-Principles](https://www.go-fair.org/fair-principles/) und den
|
||
[Ten simple rules for documenting scientific software](https://doi.org/10.1371/journal.pcbi.1006561).
|
||
|
||
Für eine Ausführliche auseinandersetzung mit dieser Thematik siehe
|
||
[BACKGROUND.md](background/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...
|