mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-08 09:59:06 +00:00
61 lines
2.2 KiB
Markdown
61 lines
2.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
|
|
|
|
Das Unterverzeichnis `example-project` enthält folgende Struktur:
|
|
|
|
```plain
|
|
example-project/
|
|
├── README.md
|
|
├── INSTALL.md (optional, bei aufwendiger Installation)
|
|
├── USAGE.md (optional, bei komplexeren Beispielen oder Workflows)
|
|
├── CONTRIBUTING.md (optional, falls Mitarbeit möglich)
|
|
├── CITATION.md (oder CITATION.cff)
|
|
├── LICENSE
|
|
├── CHANGELOG.md (optional)
|
|
├── examples/ (optional, Beispielskripte oder Notebooks)
|
|
│ └── example_workflow.ipynb
|
|
├── data/ (optional, kleine Beispieldaten)
|
|
│ └── sample_data.csv
|
|
└── src/
|
|
├── script.py
|
|
└── module/
|
|
└── helper.py
|
|
```
|
|
|
|
Die jeweiligen benötigten Dateien können einfach kopiert werden und enthalten
|
|
jeweils eine Anleitung über ihren Inhalt
|
|
|
|
## 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...
|