2.2. Dokumentation

Empfehlung

Die Entwicklung einer Forschungssoftware soll angemessen dokumentiert werden. Entwickler:innen sollen ihren Code von Anfang an dokumentieren (z. B. Funktionen beschreiben). Neben der Code-Dokumentation sind folgende Arten von Dokumentationen wesentlich:

• eine grundlegende Beschreibung der Ziele und Funktionen der Software
• die Erfassung von (standardisierten) Metadaten zur Software
• ein Nutzerhandbuch und Einstiegs-Tutorial
• ein Entwicklerhandbuch und Installationshinweise
• die Dokumentation von Dependencies

Umsetzung

• Ausführliche Dokumentation und Beschreibung der Software
• Erstellung von (standardisierten) Dokumenten wie README, CONTRIBUTING, LICENSE
• Code-Dokumentation je nach Programmiersprache mit Frameworks wie Doxygen, JavaDoc, pydoc

Möglichkeiten zur formalisierten Überprüfung

• Open SSF Badge: Abfrage von grundlegender und Referenzdokumentation https://www.bestpractices.dev/en/criteria#0.documentation_basics, Beispiel OpenSSF Gold Badge Inhaber: https://www.bestpractices.dev/de/projects?gteq=300
• fair-software.eu Badge: prüft Existenz von LICENSE
• Read the docs Badge: https://docs.readthedocs.io/en/stable/badges.html