# 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.

### 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...