mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-08 01:49:07 +00:00
89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
# Good™ Documentation
|
|
|
|
Dieses Repository enthält eine Beispielstruktur, nach welchen Regeln und in
|
|
welcher Ausführlichkeit sinnvoll dokumentiert werden sollte.
|
|
|
|
## 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.
|
|
|
|
Das Template enthält folgende Struktur:
|
|
|
|
```plain
|
|
.
|
|
├── .gitlab (issue-templates für GitLab)
|
|
├── CHANGELOG.md (CHANGELOG-Beispiel für Releases)
|
|
├── CITATION.md (Wie die Software zitieren?)
|
|
├── CONTRIBUTING.md (Wie bei der Software mithelfen?)
|
|
├── INSTALL.md (Wie die Software installieren?)
|
|
├── README.md (Genereller Überblick)
|
|
├── src (Beispielverzeichnis für den eigentlichen Code)
|
|
└── USAGE.md (Wie nutze ich die Software?)
|
|
```
|
|
|
|
Die Dateien enthalten jeweils eine Anleitung über ihren Inhalt
|
|
|
|
### Daten-Project
|
|
|
|
**Ein ähnliches Projekt für Daten-Repositories ist in Planung.**
|
|
|
|
Das Template ist für Repositories gedacht, die Daten aus Quellen erstellen,
|
|
aufbereiten und wieder zur Verfügung stellen. Beispiele wären z.b. Bilder ~>
|
|
annotierter Korpus.
|
|
|
|
Ziel ist hier die Dokumentation und die Reproduzierbarkeit von
|
|
`Quelle -> Datensatz`.
|
|
|
|
## 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`
|
|
|
|
## 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...
|