• Entwicklung/Architektur
  • Methoden
  • Programmiersprachen
• Betrieb
  • Künstliche Intelligenz
  • Datenbanken
  • Server
  • IT-Security
  • Speicher
  • Netzwerke
  • Virtualisierung
  • Verfügbarkeit
• Management und Recht
  • Projektmanagement
  • Digitalisierung
  • IT-Recht
  • IT-Selbständige
• Aktuelles
• Termine
• IT-Jobs

• Entwicklung/Architektur
• Betrieb
• Management und Recht
• News
• IT-Jobs
• Newsletter

Softwaredokumentation ist wichtig. Bis jetzt konnten Python-Programmierer immer von gut beschriebenen öffentlichen Programmbibliotheken profitieren. Da liegt es doch auf der Hand, auch den eigenen Code so zu dokumentieren, dass er in Zukunft für einen selbst und für andere lesbar und wartbar bleibt.

Bekanntlich ist der erste Schritt oft der schwierigste. Dieser Artikel soll daher eine Einführung in die Dokumentation von Python-Code geben. Er erläutert die grundlegenden Konzepte von Docstrings, der vereinfachten Auszeichnungssprache reStructuredText und dem Dokumentationsgenerator Sphinx. Zudem zeigt er die Vorteile von Docs as Code und liefert eine Antwort auf die Frage, ob Python auch mit anderen Auszeichnungssprachen dokumentiert werden kann.

Softwaredokumentation? Da war doch mal was …

So gerne ich an dieser Stelle zuerst über die Gründe, Herausforderungen und Lösungswege von Softwaredokumentation im Allgemeinen schreiben würde: In diesem Artikel, in dem es spezifisch um Python-Dokumentation gehen soll, reicht der Platz leider nicht aus. Einleitend verweise ich Sie als interessierten Leser daher hinsichtlich vieler Argumente pro Softwaredokumentation auf meinen bereits vor ein paar Jahren veröffentlichten Fachartikel "Javadoc mit Stil" – quasi das Java-Pendant zum vorliegenden Python-Artikel [1].

In Gesprächen und Beratungen stelle ich oft fest, dass v. a. in Entwicklerkreisen ein falsches Bild von Softwaredokumentation herrscht. Nicht selten haben sie in der Vergangenheit schlechte Erfahrungen gemacht, viel Aufwand investiert, aber keinen Nutzen daraus gezogen. Das ist bei Kommentaren wie

i = i + 1  # Erhöhe i um 1.

auch nicht verwunderlich.

Softwaredokumentation existiert in verschiedenen Formen; die eine Softwaredokumentation gibt es nicht. Während Mitarbeiter A unter "Dokumentation" oben gezeigte (sinnfreie) Kommentare versteht, hat sich Mitarbeiterin B darunter immer ein Übersichtsdiagramm der Businesslogik vorgestellt.

Für jeden zu erstellenden Teil der Softwaredokumentation müssen sich die Autoren daher zuerst über (mindestens) zwei Parameter bewusst werden:

• Wer – also welche Zielgruppe – soll mit dieser Dokumentation angesprochen werden?

  Endbenutzer oder externe Entwickler, die eine ausgelieferte Software oder Bibliothek benutzen, benötigen eine andere Form von Dokumentation, als es die internen Softwareentwickler oder Architekten tun. Und diese wiederum unterscheiden sich in ihrem Interesse oft deutlich von denen des Fachs, also von Product Ownern oder Managern aller Art.

• Wie detailliert – also auf welcher Ebene oder "Flughöhe" – soll dokumentiert werden?

  Während auf der höchsten Ebene die globale Softwarearchitektur bevorzugt in externen Dokumenten oder Diagrammen aufgezeigt wird, eignen sich auf Stufe Klassen, Interfaces und APIs eher Beschreibungen jeweils direkt bei ihren Definitionen. Auf der untersten Ebene haben Quellcodekommentare nach wie vor ihre Berechtigung, da sie Funktionsinterna beschreiben, die erst dann relevant sind, wenn ein Entwickler sie direkt betrachtet (und hoffentlich top-down gefunden hat). Quellcode – egal ob kommentiert oder nicht – soll niemals zur gedanklichen "Bottom-up-Rekonstruktion" der Architektur herhalten müssen.


Eine gute Orientierungshilfe, insbesondere für den Parameter "Flughöhe", bietet das C4 Model von Simon Brown [2]. Doch es gibt noch ein paar weitere grundlegende Aspekte, die eine erfolgreiche Softwaredokumentation ausmachen.

Vor wenigen Jahren habe ich die Behauptung aufgestellt: Je flexibler eine (vereinfachte) Auszeichnungssprache ist, desto komplexer ist sie auch. Den gefühlten Zusammenhang habe ich qualitativ in einem Diagramm festgehalten (s. Abb. 1).

Während das bekannte Markdown am unteren linken Ende sehr einfach in der Handhabung ist, verfügt es auch über den geringsten Funktionsumfang (und dies ist nur einer von vielen Markdown-Nachteilen). AsciiDoc und reStructuredText (RST) stellen einen idealen Kompromiss dar. Beide ermöglichen einfache Textstrukturierung und -formatierung, Gestaltung mit eigenen Stylesheets, Tabellen, mathematische Formeln, Einbetten von Quellcode (inkl. Syntax-Highlighting), Bildern, Audio und Video sowie Diagrammen.

In einem ausführlichen Fachartikel habe ich das Prinzip von (vereinfachten) Auszeichnungssprachen, deren Vergleich und die Suche nach einer universell einsetzbaren Sprache beschrieben [3]. AsciiDoc und RST stellen sich dabei als klare Sieger heraus, wobei AsciiDoc (Platz 1) etwas zugänglicher im Vergleich zum eher technikaffinen reStructuredText (Platz 2) ist.

Und wieso verwendet man nicht einfach Word oder Konsorten? Entscheidend ist, dass der Quellcode der Dokumentation in einem (auch von Menschen einfach lesbaren) Textformat vorliegt und nicht in (Binär-)Formaten, wie sie z. B. Office-Programme generieren. Liegt die Dokumentation in einem solchen Format vor, kann und soll sie gleich wie Programmquellcode behandelt werden:

• Schreiben, Lesen und Bearbeiten in der gleichen Entwicklungsumgebung (IDE)
• Verwalten und Vergleichen (diff) mit dem gleichen Versionsverwaltungssystem (meist Git)
• Integrieren in die bestehenden Prozesse, sowohl technisch (z. B. Build-Pipeline) als auch organisatorisch (z. B. Pull-Requests oder Code-Reviews)

Diesen Ansatz bezeichnet man gemeinhin als Docs as Code. In Anlehnung an dieses Konzept gibt es auch Diagrams as Code, bei dem Diagramme rein textuell beschrieben werden. Dazu gibt es je nach Diagrammtyp verschiedene Syntaxen, wobei der Kroki-Server eine einheitliche Schnittstelle zum Rendern von über 30 dieser Diagrammtypen anbietet [4]. Sie werden in den folgenden Hands-on-Beispielen auch zwei Kroki-Diagramme kennenlernen, und ich lade Sie gleich an dieser Stelle dazu ein, mit ihnen "herumzuspielen".

Oft höre ich bei Diskussionen über Softwaredokumentation das Argument, dass sie sowieso veraltet, und somit Programmcode und dessen Dokumentation "auseinanderdriften". Meistens liegt die Ursache dafür aber in der grossen Distanz zwischen dem, was zu dokumentieren ist, und dem Ort, wo es dokumentiert ist. Wenn Programmmodule "irgendwo" im Confluence beschrieben sind, ist klar, dass ein Softwareentwickler diese Dokumente dann nicht mehr findet oder nicht daran denkt, sie bei Programmänderungen nachzuführen. 

Die Lösung liegt im Konzept der quellcodenahen Dokumentation: Der Programmcode und seine Dokumentation sollen möglichst nahe zueinander stehen. Derartige Lösungen gibt es schon lange, z. B. Javadoc für Java oder JSDoc für JavaScript. Letzten Endes sind sie nichts weiter als "aufgepimpte" mehrzeilige Kommentare direkt bei den zu dokumentierenden Klassen, Methoden, Funktionen oder Ähnlichem.

Auch in Python gibt es dieses Konzept, und zwar in Form von Docstrings. Diese werden (wie jeder mehrzeilige String) mit """ eingeleitet. Im Gegensatz zu Java, wo die Javadoc-Kommentare jeweils direkt oberhalb einer Klassen- oder Methodendeklaration stehen, befinden sich Docstrings bei Python jeweils am Anfang eines Klassen- oder Funktionskörpers.

Docstrings sollten laut PEP 287 theoretisch im reStructuredText Docstring Format beschrieben werden [5]. Dieses wirkt allerdings nicht besonders elegant, weswegen NumPy und Google zwei neue Docstring-Formate hervorgebracht haben [6;7]. Werfen Sie gerne mal einen Blick in die beiden Spezifikationen. Im Beispiel 2 weiter unten werden wir auch die Dokumentation einer (bereits existierenden) Python-API erzeugen. Dort sehen Sie konkret Docstrings im Allgemeinen und das Google-Format im Speziellen.

Beide Formate sind in enger Anlehnung an den Dokumentationsgenerator Sphinx entstanden: dem Standardgenerator schlechthin für reStructuredText- und Python-Dokumentation. In einschlägiger Python-Literatur wird oft noch das help(…)-Kommando oder pydoc zum Erzeugen bzw. Ansehen von Dokumentation beschrieben. Nach meinem Dafürhalten darf man diese Tools heute zugunsten von Sphinx als obsolet betrachten.

Im folgenden Beispiel möchten wir unser erstes Sphinx-Projekt aufsetzen. Es ist zwar in einer Python-Umgebung angesiedelt, kann aber vorerst nur reine reStructuredText-Dokumente darstellen. Wie mit Sphinx Dokumentationen für Python-APIs generiert werden, zeige ich weiter unten in Beispiel 2.

Sphinx lässt sich am einfachsten als Python-Paket installieren. Mit pip geht das wie folgt:

pip install --upgrade pip setuptools
pip install sphinxcontrib-kroki
pip install sphinx_rtd_theme

In der ersten Zeile werden die beiden Paketverwaltungswerkzeuge pip und setuptools aktualisiert bzw. installiert. Letzteres wird für die Kroki-Extension sphinxcontrib-kroki in der zweiten Zeile benötigt, dort aber seltsamerweise nicht automatisch als Abhängigkeit hinzugefügt. In der dritten Zeile wird exemplarisch das Theme von Read the Docs installiert. Eine sehr gute Übersicht der eingebauten und optional installierbaren Themes für Sphinx finden Sie unter [8]. Ich werde während der Beispiele immer wieder mal die Themes wechseln, um zu zeigen, wie das geht und wie sie aussehen.

Und wo genau wird jetzt das eigentliche Sphinx installiert? Dieses ist bereits als Abhängigkeit in sphinxcontrib-kroki bzw. sphinx_rtd_theme enthalten. Ich meine, die Kroki-Extension lohnt sich immer, dabeizuhaben, aber wer unbedingt ein reines Sphinx ohne Erweiterungen oder Themes installieren möchte, kann dies einfach mit pip install Sphinx bewerkstelligen.

Im nächsten Schritt geht es darum, ein Sphinx-Initialprojekt zu erstellen. Schließen Sie davor das Terminal und öffnen es erneut, damit Ihnen nach oben beschriebener Installation auch wirklich alle Befehle (inklusive automatischer Vervollständigung) zur Verfügung stehen. Ebenfalls empfehle ich sehr, die Sphinx-Dokumentation in einem eigenen (Unter-)Verzeichnis (z. B. docs) anzulegen, weil durch das folgende sphinx-quickstart diverse weitere Verzeichnisse und Dateien erzeugt werden.

mkdir docs
cd docs
sphinx-quickstart

Der Assistent fragt in einem ersten Schritt nach der Trennung zwischen source- und build-Verzeichnissen. Für kleine Projekte sollte das keinen nennenswerten Unterschied machen, für größere gehen die Meinungen hierzu auseinander. Ich werde im Folgenden auf einer solchen Trennung bestehen und daher mit y antworten, aber Sie können später auch gerne mal die Standardvariante (mit n) ausprobieren.

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

Die folgenden drei Fragen nach Projektname, Autor(en) und Version sind selbsterklärend:

The project name will occur in several places in the built documentation.
> Project name: Informatik Aktuell
> Author name(s): Christian Heitzmann
> Project release []: 2025.02

In der abschließenden Frage möchte der Assistent wissen, in welcher Sprache die Dokumente verfasst werden. Jeder von Sphinx automatisch generierte Text wird dann auch in dieser Sprache erscheinen. Standard ist Englisch (en), für Deutsch geben wir de ein.

For a list of supported codes, see
www.sphinx-doc.org/en/master/usage/configuration.html.
> Project language [en]: de

Allgemein sollte die Wahl der Dokumentationssprache gut durchdacht sein. In einer kurzen LinkedIn-Präsentation habe ich einmal ein paar grundlegende Kriterien für die Sprachwahl bei Quellcode, Kommentaren und Dokumentation in Unternehmen zusammengestellt [9].

Ist der Assistent abgeschlossen, finden wir eine Reihe generierter Verzeichnisse und Dateien vor. Bei oben aktivierter Trennung zwischen source- und build-Verzeichnissen enthält source alle Konfigurationen und Texte von uns, während sich in build alles von Sphinx Generierte befindet. Das build-Verzeichnis lässt sich nach Gebrauch nicht nur problemlos löschen, ich empfehle es sogar ausdrücklich vor jeder Neugenerierung.

Mit make html wird jeweils die eigentliche Dokumentation erstellt – hier im HTML-Format. Diesen Schritt wiederholen Sie bitte jedes Mal, wenn Sie Änderungen an der Konfiguration oder den Textinhalten vorgenommen haben. Öffnen bzw. aktualisieren Sie anschließend in einem Webbrowser Ihrer Wahl die Datei docs/build/html/index.html, dann sehen Sie die Startseite der Dokumentation. In unserem (fast) leeren Projekt sieht sie standardmäßig noch wie in Abb. 2 gezeigt aus.

Wir möchten im Folgenden drei Konfigurationen in der Datei docs/source/conf.py ändern:

1. Das Copyright sieht in der Schreibweise ©2025, Christian Heitzmann etwas misslungen aus. Wir korrigieren das, indem wir die copyright-Variable anpassen und dabei auf das zusätzliche Leerzeichen am Anfang des Strings und das weggelassene Komma achten: 

   
copyright = ' 2025 Christian Heitzmann'  

2. Wir ändern das Theme auf die (bereits mitgelieferte) Variante Classic. Dazu wird einfach die Variable html_theme auf 'classic' geändert: 

   
html_theme = 'classic'  

3. Wir aktivieren die Extension für Kroki. Dazu muss die (noch leere) Liste extensions um den entsprechenden Eintrag 'sphinxcontrib.kroki' erweitert werden:
 

   extensions = ['sphinxcontrib.kroki']  

Zusammengefasst noch einmal die gesamte conf.py-Datei (ohne Kommentare):

project = 'Informatik Aktuell'
copyright = ' 2025 Christian Heitzmann'
author = 'Christian Heitzmann'
release = '2025.02'

extensions = ['sphinxcontrib.kroki']

templates_path = ['_templates']
exclude_patterns = []

language = 'de'

html_theme = 'classic'
html_static_path = ['_static']

Ein neuer Durchlauf von make html (im Zweifel davor immer das build-Verzeichnis löschen) führt zu einem Ergebnis wie in Abb. 3 gezeigt.

Jetzt wird es Zeit für den ersten konkreten Inhalt. Dieser wird – natürlich im Unterverzeichnis source – in Form von reStructuredText-Dateien (Dateiendung .rst) hinterlegt. Das Abhandeln der RST-Syntax würden den Rahmen dieses Artikels sprengen. Von daher stelle ich Ihnen als Leser die in diesem Artikel gezeigten Beispiele als Download zur Verfügung [10]. 

Überschreiben oder ergänzen Sie die Datei docs/source/index.rst mit dem Inhalt der Datei index.rst aus dem Download-Paket. Sie enthält ein paar typische RST-Beispiele bestehend aus Textformatierung, Listen, eingebettetem Quellcode, mathematischen Formeln und Kroki-Diagrammen. Das Ausführen von make html führt noch zu einer Warnung hinsichtlich eines nonexisting document 'modules', die wir aber für diesen Abschnitt ignorieren können. Abgesehen davon sollte ohne weitere Fehler ein umfangreiches Dokument analog Abb. 4 generiert werden.

Die Diagramme werden standardmäßig auf dem kroki.io-Server gerendert. Das ist für kleine Beispielanwendungen sicher in Ordnung, für vertrauliche Unternehmensarchitekturdiagramme aber nicht mehr. Für solche Zwecke lässt sich Kroki auch lokal installieren und betreiben [11]. In der Sphinx-conf.py-Datei müsste dann die Variable kroki_url auf den eigenen (lokalen) Kroki-Server verweisen [12].

import os
import sys
sys.path.insert(0, os.path.abspath('../../bank'))
project = 'Informatik Aktuell'
copyright = ' 2025 Christian Heitzmann'
author = 'Christian Heitzmann'
release = '2025.02'
extensions = ['sphinxcontrib.kroki', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon']
templates_path = ['_templates']
exclude_patterns = []
language = 'de'
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

Informatik-Aktuell-Dokumentation
================================
.. toctree::
  :maxdepth: 2
  :caption: Inhaltsverzeichnis
  
  modules

Indizes und Tabellen
====================
[...]

cd docs
sphinx-apidoc -o source ../bank

Das Argument -o source gibt das Zielverzeichnis für die zu erzeugende modules.rst-Datei an. Sie dient als Quelle für den darauffolgenden eigentlichen Dokumentationsgenerierungsvorgang (mit make html). Das Argument ../bank referenziert das Quellverzeichnis für die Python-Module. Ein kurzer Augenschein in die neu erzeugte Datei docs/source/modules.rst zeigt, dass ihr Inhalt relativ unspektakulär ist und lediglich das Modul bank_account referenziert. Bei größeren Applikationen mit mehr Modulen wird es dann natürlich umfangreicher.

Im letzten Schritt löschen wir das Verzeichnis /docs/build und generieren die Dokumentation mit make html neu:

rm -r build
make html

Abb. 5 zeigt das Resultat (im Read-the-Docs-Theme), welches Sie nach kurzer Navigation im Inhaltsverzeichnis ebenfalls so vorfinden.

Ab diesem Punkt empfehle ich, bei jeder, v. a. strukturellen Änderung der Python- und Dokumentationsinhalte das folgende "Kommando-Trio" auszuführen:

rm -r build; sphinx-apidoc; make html

In den beiden vorherigen Abschnitten haben Sie gelernt, wie Sie Ihre ersten Sphinx-Projekte "from scratch" aufsetzen. Natürlich lässt sich noch beliebig viel Feinschliff hineinstecken, um die Qualität der Dokumentation optisch wie inhaltlich zu erhöhen. Ich empfehle, sich ab einem gewissen systematischen Grundstock künftig an bestehender Vorzeigedokumentation zu orientieren und darin zu schauen, wie gewisse Merkmale umgesetzt werden.

Besonders empfehlen kann ich dabei die Sphinx-Dokumentationen von Python selbst, von NumPy und von pandas [13;14;15]. In den Quellen habe ich jeweils auf eine besonders gelungene Datei verwiesen. Im Rest der jeweiligen Dokumentation werden Sie sich sicherlich alleine zurechtfinden.

Da es sich bei allen Projekten um Open Source handelt, ist der Weg zu den zugrundeliegenden reStructuredText-Quellen nicht weit. Für das in [14] erwähnte NumPy-Dokument finden Sie den RST-Quellcode z. B. auf GitHub [16]. Zum Auffinden anderer Dokumentquelltexte empfehle ich eine Google-Suche mit einem charakteristischen Satz aus der Dokumentation, eingeschlossen in Anführungszeichen. 

Sphinx selbst führt auf seiner Website auch eine Liste mit einigen hunderten Python- und Nicht-Python-Projekten, die mit ihm dokumentiert wurden [17] – sogar nach Themes sortiert. Eine Übersicht der zur Verfügung stehenden Themes finden Sie unter [8].

Lässt sich Python auch mit AsciiDoc dokumentieren?

Sphinx ist reStructuredText-basiert. Bis heute sind mir keine etablierten AsciiDoc-Konvertierer, -Erweiterungen oder -Plug-ins für Sphinx bekannt. Selbst wenn es so etwas gäbe, darf ich bezweifeln, ob "AsciiDoc für Python-Docstrings" wirklich sinnvoll wäre. Die Python-Welt legt großen Wert darauf, dass Sachen "pythonic" bleiben, sprich, dass man sich an Python-Standards hält. Im Bereich der quellcodenahen Dokumentation mit Docstrings bedeutet das ganz klar reStructuredText-Syntax.

Selbst wenn AsciiDoc technisch und ergonomisch überlegen wäre (okay, nicht wäre – es ist), wäre ein solcher Stilbruch nur schwer zu rechtfertigen. Das lässt sich vergleichen mit Javadoc für Java: Es wäre schon ausgesprochen dumm, auf dieser Dokumentationsebene etwas anderes zu verwenden oder gar zu erfinden. Meines Erachtens lohnt es sich viel mehr, ein bisschen Zeit in professionelle und standardkonforme Javadoc-Kenntnisse zu investieren, z. B. in Form meines Ihnen bereits bekannten Fachartikels "Javadoc mit Stil" [1].

Allgemein empfiehlt es sich, die Verwendung einer Sprache (wie überall) möglichst einfach zu halten, im vorliegenden Fall also nicht übertriebene RST-Features zu benutzen. Zum einen muss "komplizierter" Code jeweils auch von nachfolgenden Entwicklern verstanden werden oder zumindest effizient erfassbar sein, zum anderen weicht es die Grenze zwischen RST- und AsciiDoc-Syntax etwas auf bzw. misst der Wahl der Auszeichnungssprache keine so große Bedeutung mehr zu.

Wenn AsciiDoc für Python-Projekte also keine gute Idee ist, wie sieht es dann andersherum aus: reStructuredText für jede Dokumentation?

Auf höheren Dokumentationsebenen würde das sicher funktionieren. RST ist eine vollwertige vereinfachte Auszeichnungssprache, wovon Sie sich anhand der referenzierten Beispielprojekte selbst überzeugen können. Auch für Python selbst, also auf quellcodenaher Ebene, ist reStructuredText die erste (bzw. einzige) Wahl. Problematisch ist es dann lediglich für die Dokumentation anderer Programmiersprachen. Bekanntlich werden viele Softwareprojekte heute in mehreren Sprachen programmiert. Bei vielen von ihnen ist die Dokumentationssprache (z. B. Javadoc für Java, JSDoc für JavaScript etc.) in der Regel gesetzt.

Für Multi-Language-Projekte ist also weder reines RST noch reines AsciiDoc als einzige quellcodenahe Dokumentationsauszeichnungssprache zu empfehlen. Denkbar wäre hingegen die Variante, den Programmcode jeweils mit Tags zu versehen und diese Ausschnitte dann z. B. mit AsciiDoc oder RST in externe Dokumente einzubinden. Das hätte den großen Vorteil, dass es für alle Programmiersprachen gleich funktionieren würde, AsciiDoc oder reStructuredText als einzige vereinfachte Auszeichnungssprache verwendet werden und so eine einzigartige Konsistenz über die gesamte Dokumentation hinweg erreicht werden könnte. Es bringt aber auch den Nachteil mit sich, dass die geschätzte Nähe zwischen Programmcode und Dokumentation verloren ginge, was sich aber durch die Existenz von Tags und einer gewissen Disziplin handhaben ließe. Mehr zu diesem Thema gibt es von mir sicherlich in einem zukünftigen Fachartikel oder Konferenzvortrag.

Wir sehen, diverse Entscheide betreffend die Architekturdokumentation sind grundlegend und sollten nicht "einfach mal so schnell" entschieden (oder schlimmer: gar nicht entschieden) werden. Sie bedürfen einer sorgfältigen Abklärung mit allen beteiligten Entwicklern, Projektmanagern und Stakeholdern.

1. Vereinfachte Auszeichnungssprachen – egal auf welcher Dokumentationsebene – sind für Softwaredokumentation heute unabdingbar. Ob es sich dabei um reStructuredText, AsciiDoc oder (auf niedrigerer Ebene) Javadoc und Co. handelt, ist zwar nicht matchentscheidend, aber sollte dennoch sauber evaluiert werden. Lediglich vom Einsatz von Markdown möchte ich ganz dringend abraten, da die nicht standardisierte Sprachsyntax und der sehr beschränkte Funktionsumfang ein wackeliges, wenig nachhaltiges Fundament für wachsende Dokumentationsprojekte bietet [18].
2. Jede Auszeichnungssprache hat ihr dazugehöriges Dokumentationssystem. Für reStructuredText ist das zweifelsohne Sphinx, für AsciiDoc in der Regel Antora [19], und andere Auszeichnungssprachen haben ebenso ihre "HTML-Generatoren". Es ist meines Erachtens auch völlig legitim, eine generierte Dokumentationsstruktur (wie Javadoc oder eben Sphinx) so in ihrer Einheit zu belassen und nicht um jeden Preis zu versuchen, sie z. B. nach Confluence zu exportieren.

   Ganz allgemein würde ich Confluence (und Word) im Spektrum der zur Verfügung stehenden Dokumentationslösungen mit großem Abstand auf die letzten Plätze verweisen. Das Arbeiten mit Word und Confluence steht allen Prinzipien von effizienter Softwaredokumentation entgegen. Derartige Dokumentationslösungen sind wenig nachhaltig und stellen sich früher oder später auf vielen Ebenen als Einbahnstraße heraus.

3. Schließlich braucht jede "technische" Dokumentationslösung auch entsprechende organisatorische Maßnahmen. Die wichtigste davon ist der Einsatz von wenigen, aber verantwortlichen Personen, die sich gezielt um die Dokumentation kümmern – und das gut und gerne tun. Ob diese dann als Documentation Manager, Technical Writer oder etwas humorvoll als Doctator bezeichnet werden, kann als Detail vorerst so stehen bleiben.

Christian Heitzmann

Christian Heitzmann ist zertifizierter Softwareentwickler, Technical Writer und Trainer. Als Inhaber der SimplexaCode AG dokumentiert er Softwarearchitekturen...

WinUI 3 – State of the Art

Elena Bochkor & Dr. Veikko Krypczyk

WinUI 3 ist nicht nur eine technologische Weiterentwicklung, sondern die beste Wahl, wenn moderne, performante Windows-Apps entwickelt werden sollen.

Mit User Experience zur besseren Software-Architektur

Sarah Ganter

UX ist mehr als User Interface und dessen Gestaltung. Wenn bereits im Entwicklungsprozess ein gemeinsames Verständnis im Team entsteht, dann kann UX erheblich...

Python-Code richtig dokumentieren: Docstrings, Sphinx und der Docs-as-Code-Ansatz

Christian Heitzmann

Dieser Artikel gibt eine Einführung in die Dokumentation von Python-Code und erläutert grundlegende Konzepte von Docstrings, reStructuredText und Sphinx.

Domain-Driven Design – Aggregate-Design am konkreten Beispiel

Mario Herb

Typische Abwägungen beim Schnitt der Aggregates: Wie nähern wir uns schrittweise und systematisch einem sinnvollen Design?

Domain-Driven Design – Building Blocks und die "fehlenden Patterns"

Mario Herb

In diesem Artikel schauen wir uns die klassischen Building Blocks und ergänzende Patterns an, die sich gut mit den althergebrachten Elementen kombinieren...

Pragmatisch, aber vielseitig: Architekturdokumentation mit C4

Liam Bergh

Effektive Dokumentation von Software-Architekturen mit C4: Wie diese Methode flexible Lösungen bietet, die sich an verschiedene Projektanforderungen anpassen...