Dokumentation

Welche Dokumentationsmöglichkeiten existieren?

In der Softwareentwicklung gibt es eine Vielzahl von Dokumentationsmöglichkeiten, die sich grob in zwei Hauptkategorien einteilen lassen: Dokumentation als eigenständiges Dokument und Dokumentation im Code. Beide Ansätze bieten unterschiedliche Vorteile und sollten je nach Bedarf und Kontext genutzt werden, um eine umfassende Informationsquelle zu bieten.

Im Falle der Forschungssoftware ist neben dem Aspekt der Softwaredokumentation ebenfalls die Dokumentation von mit der Software durchgeführten Experimenten eine wesentliche Aufgabe. Hierzu ist es ratsam auch Aspekte der Reproduzierbarkeit zu beachten. Einen einfachen Mechanismus hierfür liefert ein RUNME Skript, das die wesentlichen Aufgaben durchführt und für dessen Beschreibung und Dokumentation das Folgende ebenso Anwendung findet wie für die Software selbst.

Dokumentation als eigenständiges Dokument

Diese Art der Dokumentation umfasst verschiedene Dokumente, die parallel zum Code erstellt und verfügbar gemacht werden und eine breite Palette von Informationen abdecken können. Dazu gehören:

  • README-Dateien: Bieten eine Einführung und Übersicht über das Projekt, seine Ziele und wie man es nutzen oder beitragen kann. Weitere Informationen
  • Installationsanweisungen: Leiten die Nutzenden durch den Prozess der Installation der Software. Hier werden auch Abhängigkeiten der Software zu anderen Softwarepaketen und der benötigten Arbeitsumgebung aufgeführt, sofern diese nicht in einer eigenständigen Datei behandelt werden. Best Practices
  • Nutzendenhandbücher: Bieten detaillierte Anleitungen zur Nutzung der Software und erklären ihre Funktionen. Erstellung von Handbüchern
  • Contributing Dokumente: Erklären, wie Interessierte zum Projekt beitragen können, einschließlich Style Conventions und Richtlinien für Pull Requests. Beispiel Contributing Guide
  • Entwickelndendokumentationen: Bieten technische Details und Erklärungen für Entwickelnde, die am Projekt arbeiten oder es erweitern möchten. Diese Dokumentationen können sowohl intern (für Teammitglieder) als auch extern (für die Entwicklergemeinschaft) ausgerichtet sein. Wichtig ist ab einer gewissen Projektgöße auch Teamhierachien abzubilden (Kernentwickelnde, Modulverantwortliche; Qualitätskontrolle und Testing)

Abschliessend eine Liste allgemeiner Leitfäden zur Erstellung von Dokumentationen:

Dokumentation im Code

Diese Form der Dokumentation ist direkt im Quellcode eingebettet und umfasst:

  • Variablen- und Funktionsnamen: Sollten so gewählt werden, dass sie selbsterklärend sind und den Zweck oder die Funktion des Code-Elements verdeutlichen. Namenskonventionen
  • Docstrings und Annotations: Bieten Erklärungen und Kontext für Funktionen, Klassen und Module direkt im Code. Sie sind besonders nützlich da für viele Sprachen Werkzeuge (siehe unten) existieren, die genutzt werden können, um aus ihnen automatisch Dokumentation zu generieren.
  • Kommentare: Bieten zusätzliche Erklärungen oder Kontext zu bestimmten Codeabschnitten oder -blöcken, die möglicherweise nicht sofort verständlich sind. Kommentare sollten nicht umgangssprachliche Formulierungen einzelner Codezeilen sein, sondern eher die Ideen oder das Konzept hinter einem Codeblock erklären. Sie können auch dazu dienen, temporäre Hinweise oder TODOs für zukünftige Überarbeitungen zu hinterlassen. Gute Kommentarpraktiken

Dokumentation im wissenschaftlichen Umfeld

Beide Dokumentationsarten spielen eine wichtige Rolle in der Softwareentwicklung und -verwendung. Während die Dokumentation als eigenständiges Dokument eine breite Übersicht und detaillierte Anleitungen bietet, ermöglicht die Dokumentation im Code ein tieferes Verständnis der Funktionsweise und der internen Struktur des Projekts. Die bisherige Darstellung ist allerdings generisch auf jedwede Art von Software anwendbar. Wo liegen also die speziellen Anforderungen an Dokumentation wissenschaftlicher Software? Für allgemeine Software erstellt oft ein vergleichsweise kleines Team von Entwickelnden und Beitragenden die Software für eine weit größere Gruppe von Anwendenden. Damit liegt auch der Fokus der Dokumentation sehr stark auf den Installationsanweisungen und Nutzendenhandbüchern. Die Anwendenden von Wissenschaftssoftware sind dagegen häufig kaum mehr als die Entwickelnden selbst. Außerdem wird gerade bei kleinen Projekten oft eine Software aus der Feder Promotionstudierender von der ihnen nachfolgenden Generation nachgenutzt und weiterentwickelt. Eine Co-Existenz von Entwickelnden und Anwendenden ist damit wesentlich weniger wahrscheinlich, als bei allgemeiner Software. Außerdem ist es bei allgemeiner Software in der Regel ausreichend, dass EIN brauchbares Ergebnis erzielt wird. Für den Wisschenschaftprozess ist aber die möglichst genaue Reproduktion des exakten Ergebnisses eines Computer-Experiments, oder einer Datenauswertung von extremer Wichtigkeit. In der Konsquenz verschiebt sich der Fokus der Dokumentation weit mehr zur Dokumentation der Entstehungsprozesse und Entwickelndendokumentationen. Zu beantwortende Fragen sind:

  • Welche Forschungsfrage soll beantwortet werden?
  • Welche möglicherweise vereinfachenden Annahmen wurden gemacht und müssen gegebenenfalls in folgenden Errweiterungen überdacht, entfernt oder schlicht berücksichtigt werden?

Oft hängt die Entwicklung direkt an Fördergeldern und mit deren Auslaufen ruht auch das Softwareprojekt (idealerweise vorübergehend). Daher erfolgt in der Regel keine direkt Übergabe durch Bearbeitende an ihre Nachfolgenden. Auch hier ergeben sich zusätzliche Anforderungen an die Prozessdokumentation. Neben den bereits erwähnten Fragen zur Reproduzierbarkeit stehen hier auch Fragen der Nachvollziehbarkeit, etwa von Designentscheidungen oder Deployment Prozeduren, im Mittelpunkt. Wichtig ist aber auch die Dokumentation von Authentifikationen und Berechtigungen in solcehn Prozessen.

Welche Anforderungen gibt es an die Dokumentation von Software?

Die Anforderungen an die Dokumentation von Software sind vielfältig und umfassen verschiedene Dokumentationstypen wie Schnittstellen-Dokumentationen, Howtos, Tutorials und Getting Started Guides für Nutzende, Prozessdokumentationen, Codes of Conduct und Style Guides für Entwickelnde. Es gibt zahlreiche Vorschläge, Ansätze und Best Practices für effektive Dokumentation, darunter ARC24/C4, das Divio Documentation System, und Architecture Decision Records. Es ist wichtig zu betonen das selbst dokumentierender Code wichtig, aber kein Allheilmittel ist (Limits of self-documenting code).

Die Sprache der Dokumentation sollte in der Regel Englisch sein, wobei Nutzendenhandbücher gegebenenfalls auch in Englisch und der Muttersprache der jeweiligen Zielgruppe verfügbar sein sollten. Es ist wichtig, ethische Aspekte, wie die Vermeidung von Diskriminierung, zu berücksichtigen und nicht einfach “auf Halde” zu dokumentieren, sondern stets die Zielgruppe des jeweiligen Dokumentationstyps vor Augen zu behalten und deren Kenntnisse über das Projekt sowie Ansprüche an selbiges zu berücksichtigen. Darüberhinaus sollte wohlüberlegt sein welche Dokumentationstypen bereit gestellt werden, um den Mehraufwand für Erzeugung und insbesondere Pflege der Dokumentation überschaubar zu halten. Erste Regel muss aber sein, dass jede Form von Dokumentation stets parallel zum Code fortgeschrieben wird. Schlimmer als fehlende Dokumentation ist fehlerhafte, und damit irreführende, Dokumentation.

Wichtig im Hinblick auf die gute Wissenschaftliche Praxis:

Welche Software unterstützt beim Schreiben von Dokumentationen?

Beim Schreiben von Dokumentationen, insbesondere für Programmierschnittstellen (APIs), können verschiedene Softwaretools unterstützen, die hier in alphabetischer Reihenfolge aufgeführt sind:

  • doxygen: Ein Dokumentationsgenerator, der verwendet wird, um Dokumentation aus annotierten Quellcodedateien zu erstellen. Er unterstützt mehrere Programmiersprachen, darunter C++, C, Java, Objective-C, Python und andere. Doxygen kann sowohl die Struktur eines Programms aus dem Quellcode extrahieren als auch die Dokumentation aus im Code eingebetteten strukturierten Kommentaren generieren, um technische Dokumentation in verschiedenen Formaten wie HTML und LaTeX zu erstellen. Mehr über doxygen
  • javadoc: Ein Dokumentationsgenerator für Java-Code, der aus Java-Quellcode HTML-Dokumentationen erstellt. Javadoc nutzt spezielle Kommentare im Quellcode, um die Dokumentation zu generieren und bietet so eine standardisierte Methode, um Java-APIs zu dokumentieren. Mehr über javadoc
  • pydoc: Ähnlich wie javadoc, aber für Python. Pydoc generiert automatisch Dokumentation aus Python-Modulen. Die Dokumentation kann als Text im Terminal oder als HTML-Seite angezeigt werden. Pydoc nutzt die docstrings, die in Python-Code eingebettet sind, um Informationen über Funktionen, Klassen und Module zu extrahieren. Mehr über pydoc
  • Swagger (heute bekannt als OpenAPI Specification): Ein Toolkit zur Design-, Build-, Dokumentations- und Nutzungsdokumentation von RESTful Web Services. Swagger ermöglicht es Entwicklern, die Struktur ihrer APIs zu beschreiben, so dass Maschinen sie verstehen können, was die Erstellung von Dokumentationen und SDKs erleichtert und die Entdeckung und Nutzung von APIs verbessert. Mehr über Swagger/OpenAPI
  • UML (Unified Modeling Language): Eine standardisierte Modellierungssprache, die es ermöglicht, die Struktur und das Design von Software visuell darzustellen. UML bietet verschiedene Diagrammtypen, um verschiedene Aspekte eines Systems zu visualisieren, einschließlich Klassendiagramme, Sequenzdiagramme und Anwendungsfalldiagramme. Mehr über UML

Allen diesen Werkzeugen ist gemein, dass sie das resultierende Dokument aus Code-Bestandteilen und/oder Code-Annotationen generieren, um den Overhead für das Schreiben der Dokumentation zu minimieren.

Wo kann ich Dokumentation öffentlich zur Verfügung stellen?

Die Veröffentlichung der Dokumentation sollte idealerweise “nahe” am Code erfolgen, beispielsweise im gleichen Repository. Desweiteren bieten CI-basierte Lösungen aus dem Repository, wie etwa readthedocs.com oder github.io eine automatisierte Möglichkeit, Dokumentationen aktuell zu halten. Wird die Software ohnehin auf den GitLab Instanzen von GWDG und MPCDF entwickelt, bietet es sich an, die Dokumentation ebenfals dort als GitLab Pages bereitzustellen.

Lokale Lösungen wie der integrierte Hilfebrowser von MATLABs oder GNU Octaves integrierter Entwicklungsumgebung (IDE) sind ebenfalls gute Optionen, Dokumentation nah am Arbeitsumfeld der Entwickelnden und Anwendenden zu halten.

Wichtig erscheint es aber grundsätzlich Dokumentation (öffentlich) bereit zu stellen, da dies einerseits vermeidet, das Nutzer diese selbst mit obigen Werkzeugen erzeugen müssen (Versionsunterschiede können hier fatale folgen haben, oder hohe Zeitaufwände erzeugen) und im Fall öffentlicher Verfügbarmachung, etwa auf zentralen Dokumentationsservern oder Community-Plattformen, wird zusätzliche Sichtbarkeit für die Software generiert.

Wie sollte ich die Dokumentation lizenzieren?

Die Lizenzierung der Dokumentation sollte, soweit möglich, ähnlich wie die der Software selbst erfolgen. Alternativ können Creative Commons (CC) Lizenzen (CC BY/CC0) verwendet werden. Ein Haftungsausschluss in der Dokumentation ist ebenso wichtig wie in der Softwarelizenzierung, wobei CC-Lizenzen bereits einen solchen im Volltext enthalten, wie z.B. Ziffer 5 im Fall CC BY 4.0. Wird Max-Planck-Innovation für die Kommerzialisierung der Software eingeschaltet kann auch die Dokumentation als Know-How mit lizenziert werden. Dann wird auch diese mit einer proprietären Lizenz versehen.

Wie sollte Dokumentation geschrieben werden, um Diskriminierung zu vermeiden und vorzubeugen?

Um Diskriminierung zu vermeiden und vorzubeugen, sollte bei der Erstellung von Dokumentationen auf eine umsichtige Auswahl von Beispielen, geschlechterneutrale Sprache und die Vermeidung diskriminierender Begrifflichkeiten wie “master-slave” geachtet werden, und stattdessen Alternativen wie “hub-spokes” oder “main-subordinate” bevorzugt werden.

FORS  IT4SCIENCE  GWP4RSE  FAQ  Dokumentation