Dokumentieren

Damit Euer Produkt sinnvoll genutzt werden kann, sind Dokumentationen sowohl für die Zielgruppen Daten-Wissenschaftler und Daten-Ingenieure als auch für System-Ingenieure erforderlich:

  • Daten-Wissenschaftler wollen dokumentiert sehen

    • welche Probleme Euer Produkt löst und was die Hauptfunktionen und Limitationen der Software sind (README)

    • wie das Produkt beispielhaft verwendet werden kann

    • welche Veränderungen in aktuelleren Software-Versionen gekommen sind (CHANGELOG)

  • Daten-Ingenieure wollen wissen, wie sie mit Fehlerbehebungen zur Verbesserung des Produkts beitragen können (CONTRIBUTING) und wie sie mit anderen kommunizieren (CODE_OF_CONDUCT) können

  • System-Ingenieure benötigen eine Installationsanleitung für Euer Produkt und der erforderlichen Abhängigkeiten

Alle gemeinsam benötigen Informationen, wie das Produkt lizenziert ist (LICENSE-Datei oder LICENSES-Ordner) und wie sie bei Bedarf Hilfe erhalten können.

Um schnell einen Überblick übr ein Produkt zu erhalten, sind sog. Badges hilfreich. Für das cookiecutter-namespace-template sind dies z.B.:

Downloads Updates Versions Contributors License Docs

Für umfangreiche Dokuemtationen könnt Ihr z.B. Sphinx verwenden, ein Dokumentationswerkzeug, das reStructuredText, eine einfache Auszeichnungssprache, in HTML oder auch PDF, EPub und Manpages umwandelt. Auch das Jupyter-Tutorial ist mit Sphinx erstellt worden. Um einen ersten Eindruck von Sphinx zu erhalten, könnt Ihr Euch den Quellcode dieser Seite anschauen indem Ihr am Fuss dieser Seite dem Link Sources folgt.

Ursprünglich wurde Sphinx für die Dokumentation von Python entwickelt und wird heute auch in fast allen Python-Projekten verwendet, u.a. für NumPy und SciPy, Matplotlib, Pandas und SQLAlchemy.

Zur Verbreitung von Sphinx unter den Python-Entwicklern dürfte auch das Sphinx autodoc-Feature beigetragen haben, mit dem Dokumentationen aus Python Docstrings erzeugt werden können. Insgesamt erlaubt Sphinx Entwicklern, in place eine vollständige Dokumentation erstellen zu können. Häufig wird die Dokumentation auch im selben Git-Repository gespeichert, sodass das Erstellen der jeweils aktuellen Software-Dokumentation einfach bleibt.

Sphinx wird auch in Projekten außerhalb der Python-Community verwendet, z.B. für die Dokumentation des Linux Kernels: Kernel documentation update.

Um die Erstellung von Dokumentationen weiter zu vereinfachen, wurde Read the Docs entwickelt. Read the Docs vereinfacht das Erstellen und Veröffentlichen von Dokumentation nach jedem Commit.