---
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  
   ![](imgs/use_template_1.png)
2. Aus Template  
   ![](imgs/use_template_2.png)
3. Gruppe wählen  
   ![](imgs/use_template_3.png)
4. Template auswählen & erstellen  
   ![](imgs/use_template_4.png)

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