Ausgezeichnete Softwaredokumentation

Dokumentationsschulden und ihre Ausreden

Jeder Tag, an dem nicht dokumentiert wird, erhöht den Schuldenberg der Software. Diese Schulden werden von Tag zu Tag grösser. Wenn es einen selbst nicht trifft, dann die Kollegen, allen voran die neuen.

Dieses Muster wiederholt sich so lange, bis eines Tages der Punkt erreicht ist, an dem Reverse Engineering den grössten Teil der Arbeitszeit in Anspruch nimmt. Von effizienter Softwareentwicklung kann spätestens ab dann keine Rede mehr sein.

Dokumentationsschulden sind technische Schulden – mit allen Konsequenzen [1].

Betrachten wir die typische Arbeitssituation eines neuen Softwareentwicklers. In der Bewerbungsphase wird ihm noch das Blaue vom Himmel versprochen. Am ersten Arbeitstag geht es darum, seinen Arbeitsplatzrechner aufzusetzen. Im besten (wenn auch in keinem optimalen) Fall gibt es ein Festplatten-Image, im schlechtesten Fall müssen Mitarbeiter um Hilfe gebeten werden. Im typischen Fall sind die Wiki-Seiten, auf denen die Installation beschrieben wäre, veraltet oder unvollständig und damit praktisch unbrauchbar.
Im ersten Monat versucht unser neuer Softwareentwickler, ein erstes Verständnis der „Architektur“ zu erlangen. Es gibt weder eine Architekturübersicht noch API- oder Quellcodekommentare. Er nimmt sich daher allen Mut zusammen und spricht seine Kollegen auf die fehlende Dokumentation an. Im höflichsten Fall bekommt er dann die nüchterne Antwort: „Wir machen das bei uns nicht.“ In allen anderen Fällen wird er sich die eine oder andere Form von „&$!#%“ anhören müssen.

Ab diesem Zeitpunkt wird sich besagter Entwickler tagein, tagaus für alle darauffolgenden Monate und Jahre in diesem Unternehmen mit Reverse Engineering beschäftigen müssen. Aber jetzt mal Hand aufs Herz: Das muss doch besser gehen, oder?

IT-Unternehmen entgegnen ihrer Pflicht zur Softwaredokumentation meist mit einer oder mehrerer dieser drei Ausreden:

1. „Wir sind agil!“

   Wer so argumentiert, hat „agil“ nicht verstanden. Nirgendwo, auch nicht im Manifesto for Agile Software Development, ist oder war jemals die Rede davon, dass bei agilen Methoden die Softwaredokumentation ausgelassen werden kann. Agil heisst nicht keine Dokumentation.

2. „Keine Zeit!“ / „Kein Geld!“

   Je nach Auftragslage wird die eine oder die andere Ausrede hervorgeholt. Geht es gerade aufwärts, fehlt für die Dokumentation offenbar die Zeit. Geht es gerade abwärts, fehlt dafür offenbar das Geld. Mit anderen Worten: Die Software oder Infrastruktur wird nie dokumentiert.Dabei ist die Rechnung ganz einfach, sobald sich ein Entscheider traut, ohne rosarote Brille den Effizienzverlust in der Softwareentwicklung wahrzunehmen; zusammen mit allen anderen Risiken wie Programmierfehler, „Dirty Hacks“, Antipatterns und Sicherheitslücken, die nur wegen des mangelnden Architekturüberblicks und -verständnisses entstehen.

3. „Wir machen Clean Code / TDD / XP / [you name it]. Der Code ist die Dokumentation!“

   Diese Diskussion ist genauso ermüdend und wenig zielführend wie Diskussionen mit Flat-Earthers oder Systemverweigerern. Ich habe – allen Beschwichtigungen zum Trotz – bis heute noch nie gesehen, dass obige Behauptung jemals zutreffend gewesen wäre. Selbst wenn sie im Kleinen (auf Funktionsebene) noch funktionieren würde: der Architekturüberblick ergibt sich damit noch immer nicht. Von daher: Träumt weiter!

In zwei meiner Fachartikel zu Softwaredokumentation, die in Java-SPEKTRUM bzw. IT Spektrum erschienen sind, führe ich eine ganze Liste von (unbestreibaren) Gründen für Dokumentation aus. Sie können diese Artikel gerne unter [2] und [3] herunterladen und lesen.

Einen starken Punkt für alle Entscheider möchte ich gleich an dieser Stelle wiedergeben: Gemäss den Grundsätzen zur Bewertung immaterieller Vermögenswerte vom Institut der Wirtschaftsprüfer (IDW) ist eine „ausreichende und für einen sachverständigen Dritten nachvollziehbare Dokumentation“ unabdingbar. „Nur wenn entsprechende Unterlagen die Weitergabe der Kenntnisse auch ohne Mitwirkung der Mitarbeiter ermöglichen, ist davon auszugehen, dass das Unternehmen über die Technologie verfügen kann“ [4].

Salopp lässt sich das auch so ausdrücken: Ist die Technologie oder Software für aussenstehende Dritte nicht sauber dokumentiert, gilt sie im Rahmen einer Due Diligence als wertlos. Wenn das mal kein starker Tobak ist …

Zielgruppen und Flughöhen

Softwaredokumentation ist nicht gleich Softwaredokumentation. Grundsätzlich müssen mindestens zwei Parameter unterschieden werden.

1. Zielgruppe: Wer soll angesprochen werden?
   Handelt es sich um aussenstehende Entwickler (welche die Software z. B. via API-Aufrufen oder als Bibliothek für deren eigene Software weiterverwenden) oder um Endbenutzer? Soll die Dokumentation die „Techniker“ oder doch eher die businessaffinen Product Owner und Manager adressieren? Und welche Form von Dokumentation benötigen die eigenen Entwickler, insbesondere neue Mitarbeiter?Der gesamte regulatorische und Compliance-Bereich wäre hier ebenfalls zu erwähnen, was ich jedoch im Rahmen dieses Artikels ausspare, da es schlicht nicht meine Welt ist. Mit den vorgestellten Methoden und Werkzeugen lässt sich jedoch auch dieses Feld hervorragend schriftlich festhalten.
2. Flughöhe: Wie detailliert soll dokumentiert werden?
   Die globale Softwarearchitektur, die top-down eine gute Übersicht liefern soll, wird bevorzugt in externen Dokumenten und darin eingebetteten Diagrammen beschrieben. Mit einem solchen Architekturüberblick sollen Leser – allen voran neue Mitarbeiter – ohne weiteren grossen Rechercheaufwand in der Lage sein, den grundlegenden Aufbau und die grundlegende Funktionsweise der Software- und Systemlandschaft zu verstehen.Meist scheitert es bei Softwareunternehmen bereits auf dieser Stufe. So bleibt (neuen) Mitarbeitern nichts anderes übrig, als in mühevoller Kleinarbeit die grundlegende Funktionsweise durch viele kleine Puzzlesteine auf niedriger Ebene gedanklich wieder zu rekonstruieren. Das ist – sofern es überhaupt funktioniert – nicht nur unglaublich zeitaufwendig und damit teuer, sondern auch hochgradig fragil und unsicher; und gegenüber den betroffenen Mitarbeitern in höchstem Masse respektlos.Klassen, Interfaces und APIs werden quellcodenah in der für die jeweilige Programmiersprache gängigen Dokumentationssprache beschrieben, oft HTML in Kombination mit Javadoc- (bei Java) oder JSDoc-Tags (bei JavaScript). Ziel derartiger Beschreibungen soll es sein, ohne Einsicht in den Quellcode zweifelsfrei erkennen zu können, für was eine Klasse, Methode und API-Schnittstelle zuständig ist, was als deren Eingabe erwartet wird, was zurückgegeben wird und welche Rahmenbedingungen zu beachten sind.

   Die Dokumentationen populärer Softwarebibliotheken (in Java inklusive des JDKs selbst) dienen oft schon als gute Vorbilder, denn diese Bibliotheken lassen sich praktisch immer ohne Konsultation ihres Quellcodes benutzen. Wieso also sollte für die hausinterne Software ein anderer Massstab gelten?

   Auf der niedrigsten Stufe werden die Funktionsinterna beschrieben, die ausser den Entwicklern an dieser Stelle – salopp gesagt – niemanden interessieren und auch niemanden zu interessieren haben. Dokumentation auf dieser Stufe erfolgt in Form von Quellcodekommentaren.

Die Wahl der Zielgruppe und der Flughöhe ist kein „Entscheid“ – vielmehr haben für eine vollständige Dokumentation die diversen Kombinationen dieser beiden Parameter in verschiedenen Dokumenten parallel zu existieren. Wer dokumentationstechnisch noch auf einer grünen Wiese steht, sollte mit derjenigen Zielgruppen-Flughöhen-Kombination beginnen, bei der aktuell am meisten der Schuh drückt.

(Vereinfachte) Auszeichnungssprachen

Für ausgezeichnete Softwaredokumentation sind (vereinfachte) Auszeichnungssprachen essenziell. Daher rührt der Titel mit seinem Wortspiel. Doch was ist überhaupt eine solche Sprache?

Unter einer Auszeichnungssprache (engl. markup language) versteht man eine maschinen- und menschenlesbare Sprache für die Gliederung und Formatierung von Texten und anderen Daten. Die bekannteste Vertreterin der Auszeichnungssprachen ist wohl die Hypertext Markup Language, kurz HTML. Abbildung 1 zeigt den HTML-Code einer ComConsult-Webseite.

Der grosse Vorteil ist, dass sämtliche „Einstellungen“ oder „Parameter“ offengelegt und mit (nötigenfalls geübtem) Menschenauge erkennbar sind, ganz im Gegensatz zu Binärformaten, wie sie z. B. Word produziert. Wahrscheinlich hat jeder schon die Erfahrung gemacht, dass in Word-Dokumenten mit der Zeit „komische“ Einstellungen entstehen, die man nur durch viel Herumklicken (oder gar nicht mehr) nachvollziehen resp. ändern kann. Aus Nachhaltigkeits- und Dokumentationsperspektive sind derartige Binärdateiformate inakzeptabel.

Ein weiteres Beispiel für eine Auszeichnungssprache ist LaTeX. Vielleicht kennt der eine oder andere Leser dies noch aus seinem Studium, wo es v. a. in technischen Studiengängen für Abschlussarbeiten und wissenschaftliche Papers recht verbreitet ist. Seine Syntax ist hingegen auch nach Jahren der Übung noch immer schwerfällig, weswegen ich jeden verstehen kann, der sich nicht (mehr) damit herumschlagen möchte.

Um das Problem der erschwerten Lese- und Schreibarbeit zu adressieren, wurden vereinfachte Auszeichnungssprachen (engl. lightweight markup language) erfunden. Sie zeichnen sich durch eine einfachere Syntax ohne Störung des Schreib- und Leseflusses aus. Der bekannteste Vertreter ist wohl Markdown, doch auch die Artikel der weltbekannten Wikipedia werden in einer vereinfachten Auszeichnungssprache (namentlich MediaWiki) verfasst. Wer Jira kennt, ist höchstwahrscheinlich auch mit der dort verwendeten Jira Formatting Notation vertraut.

Das Diagramm in Abbildung 2 zeigt einen gefühlten Zusammenhang zwischen der Flexibiliät und Komplexität ausgewählter (vereinfachter) Auszeichnungssprachen. Je flexibler eine Auszeichnungssprache, d. h. je mehr Gestaltungsmöglichkeiten sie bietet, desto „komplizierter“ ist sie auch. LaTeX bildet – wie bereits erwähnt – das obere Extrem, während Markdown aufgrund seines sehr kleinen Funktionsumfanges das untere Extrem darstellt. Beide Sprachen sind für unseren Anspruch an ausgezeichnete Softwaredokumentation ungeeignet. Vielmehr suchen wir einen guten Kompromiss – und den gibt es!

AsciiDoc

In einem ausführlichen Fachartikel für die Zeitschrift IT Spektrum, den Sie gerne herunterladen dürfen, habe ich die diversen zur Verfügung stehenden vereinfachten Auszeichnungssprachen – es sind mittlerweile über 20 – einmal miteinander verglichen [3]. Mein Anspruch war, eine Sprache nicht nur für Softwareentwickler, sondern für jedermann zu finden. AsciiDoc hat sich dabei als klarer Sieger herausgestellt, gefolgt von reStructuredText.

Ich stelle Ihnen, liebe Leserinnen und Leser, vorliegenden Artikel auch direkt im AsciiDoc-Format zum Herunterladen zur Verfügung [5]. Dann können Sie sich gleich selbst von der Einfachheit der Sprache überzeugen. Sie werden sehen, dass Sie auch, ohne das Dokument zu generieren, seinen Aufbau erkennen und in „Rohform“ alles lesen und bei Bedarf bearbeiten können.

Zu den Möglichkeiten, die AsciiDoc bietet, zählen unter anderem:

1. Textstrukturierung und -formatierung
2. Tabellen
3. Einbetten von Quellcode (inkl. Syntax-Highlighting)
4. Diagramme
5. mathematische Formeln
6. Gestaltung mit eigenen Stylesheets
7. Einbetten von Bildern, Audio und Video
8. Erstellen von Präsentationen (via reveal.js)

Punkt 1 können Sie einsehen, wenn Sie – wie oben angeboten – den vorliegenden Artikel im AsciiDoc-Format herunterladen [5]. Zu den Punkten 2 bis 5 finden Sie rechts Beispiele im Asciidoc-Format sowie in der Abbildung 3 die daraus generierten Resultate.

Docs as Code und Diagrams as Code

Obiges Listing bestätigt das bereits Gesagte, nämlich dass die Dokumente ausschliesslich „programmiert“ werden. Eine Maus, wie sie z. B. in Word oder PowerPoint zwingend ist, um überhaupt erst Einstellungen oder Anordnungen vornehmen zu können, ist hier weder notwendig noch erlaubt.

Liegen die Dokumente ausschliesslich im Textformat (und nicht in einem Binärformat wie bei Word) vor, spricht man von Docs as Code – Dokumente werden wie Quellcode behandelt. Vor allem im Bereich der Softwaredokumentation hat das viele entscheidende Vorteile:

• Entwickler können die Dokumente in der gleichen Entwicklungsumgebung (IDE) erstellen und bearbeiten, die sie sonst auch zum Programmieren verwenden.
• Dokumentenquellcodes können der gleichen Versionsverwaltung wie die der Applikationsquellcodes unterstellt werden. So lässt sich einfach jeder Versionsstand aus der Vergangenheit – synchron zum Programmcode – reproduzieren und verschiedene Versionsstände untereinander vergleichen. Dadurch ist sofort ersichtlich, was wo geändert wurde.
• Dokumentationsänderungen können in die gleichen organisatorischen Prozesse wie Applikationsänderungen integriert werden, allen voran bei Pull-Requests bzw. Code-Reviews. Dokumentation benötigt nämlich genauso ein Qualitätsmanagement wie Programmcode.
• Die Generierung der Dokumente kann in die bereits vorhandene CI/CD-Pipeline integriert werden. Mit jedem neuen Build wird der jeweils aktuelle Stand der Dokumentation erstellt und auf diverse Plattformen exportiert.

Im Beispiel aus dem vorherigen Abschnitt ist auch ein kleines UML-Diagramm zu sehen. Werden Diagramme textuell beschrieben, dann spricht man von Diagrams as Code. Ihre Erstellung – ganz ohne Maus – mag anfangs gewöhnungsbedürftig sein, hat aber neben den oben erwähnten Punkten den zusätzlichen Vorteil, dass sie vollständig automatisierbar ist. Denkbar wäre das automatisierte Auslesen von Konfigurationen aus einer Datenbank, das „textuelle Verfassen“ des Diagramms mithilfe eines kleinen Programms basierend auf diesen Daten und abschliessend dessen grafische Generierung (was bei einer Einbettung in ein AsciiDoc-Dokument implizit geschieht). Veraltete Grafiken, die nicht mehr den Stand der eigentlich zu beschreibenden Datenbasis wiedergeben, gehören damit der Vergangenheit an.

Welche Diagrammtypen lassen sich einem solchen Diagrams-as-Code-Ansatz folgend erstellen? Bilder sagen bekanntlich mehr als 1000 Worte, weshalb ich Ihnen an dieser Stelle nur wärmstens empfehlen kann, die Sammlung von Beispielen auf [6] anzusehen.

„Aber wir haben doch schon Confluence!“

So nachvollziehbar der Wunsch nach einer einzigen Dokumentationsablage auch sein mag, realistisch ist er leider nicht. In der Softwareentwicklung gibt es (aus guten Gründen) verschiedene Programmiersprachen, denn jede Sprache hat ihre eigenen Stärken und Schwächen in den verschiedenen Anwendungsbereichen der IT.

Übertragen auf die Softwaredokumentation (niedriger Flughöhe) haben sich für diverse Programmiersprachen auch diverse Dokumentationsumgebungen als Quasistandards etabliert:

• Java – Javadoc mit HTML und definierten Javadoc-Tags
• Python – Docstrings in reStructuredText-Syntax
• C#/.NET – XML Documentation Comments mit definierten XML-Tags
• JavaScript – JSDoc mit HTML und definierten JSDoc-Tags

Allen aufgezählten Dokumentationslösungen ist die (für ihre Flughöhe charakteristische) Nähe zwischen Quellcode und Dokumentation gemeinsam. Die Dokumentation wird dabei entweder „in Rohform“ beim dazugehörigen Quellcode in der Entwicklungsumgebung (IDE) gelesen, oder die von den speziellen Dokumentationgeneratoren erzeugten HTML-Seiten werden direkt im Webbrowser betrachtet. Ein Export solcher in sich abgeschlossener Dokumentationstrukturen nach Confluence, SharePoint oder dergleichen ist weder üblich noch sinnvoll.

Leicht anders verhält es sich mit „allgemeiner“ Dokumentation (höherer Flughöhe), die nicht mehr an eine Programmiersprache gekoppelt ist. Als „General Purpose Language“ empfehle ich (wie in diesem Artikel jetzt sicherlich klar wurde) AsciiDoc. Unternehmen, deren Projekte in der Python-Landschaft zuhause sind, können jedoch meine Ausführungen auch auf die dort etablierte vereinfachte Auszeichnungssprache reStructuredText übertragen.

Mit AsciiDoc erstellte Dokumente lassen sich problemlos in einer Build-Pipieline nach Confluence exportieren. Dabei ist zu beachten, dass die so einsehbaren Confluence-Seiten nur als read-only behandelt werden sollen, d. h. Änderungen der Dokumente müssen immer im AsciiDoc-Master und dürfen niemals direkt im Confluence-Editor erfolgen; sonst werden sie beim nächsten Export-Vorgang durch die Pipeline gleich wieder überschrieben.

Antora

Ein hervorragendes Dokumentationssystem für AsciiDoc stellt Antora dar. Antora kann aus verschiedenen Versionsverwaltungssystemen AsciiDoc-Dokumente zusammentragen und daraus statische HTML-Seiten generieren. Der grosse Vorteil besteht darin, dass beim Betrachten der Versionsstand mit einem einzigen Klick im Webbrowser ausgewählt werden kann, und dann direkt die für die ausgewählte Version passende Dokumentation erscheint. Beispiele für öffentlich einsehbare Antora-Dokumentationsstrukturen mit angepasstem UI finden Sie unter [7] und [8], solche mit Standard-UI unter [9] und [10].

So wie es Sinn ergibt, im Haushalt verschiedene Ablagesysteme für verschiedene „Gegenstandskategorien“ zu haben (z. B. Bücherregal für Bücher, Aktenordner für Einzeldokumente, Körbe für Schmutzwäsche), so ist das oft auch für elektronische Dokumentation sinnvoll. Eine in sich geschlossene Einheit kann nämlich sehr motivierend sein, (zumindest) darin Ordnung zu halten. Von diversen Unternehmen und Erzählungen kenne ich Confluence und andere Firmenwikis hingegen fast nur als unorganisiertes Sammelbecken für Dokumente jeglicher Art. Nicht umsonst behaupten böse Zungen, dass „Wiki“ eigentlich ein Akronym für „Where information kills itself“ ist.

Statische HTML-Dokumente, wie sie Antora erstellt, können einfach auf diversen Plattformen veröffentlicht werden. Mit Confluence hingegen lassen sich nur einzelne Seiten, nicht aber zusammenhängende Dokumentationsbäume freischalten.

Zuletzt gilt es zu berücksichtigen, dass in Confluence erstellte Dokumente einer „Einbahnstrasse“ gleichkommen. Sind sie einmal im System, können sie nicht mehr in einem sinnvollen Format extrahiert werden. Die Gefahr eines solchen Vendor-Lock-ins ist beträchtlich.

Infrastructure as Code am Beispiel von Docker

Wird die Software-Infrastruktur textuell beschrieben, sodass Plattformen wie Docker vollautomatisch Software als Images erstellen, verknüpfen und ausführen können, so spricht man in Anlehnung an Docs as Code und Diagrams as Code hier analog von Infrastructure as Code. Eine derartige Beschreibung stellt eine implizite Dokumentation dar, denn alle Schritte, die zum Aufsetzen einer Softwarelandschaft benötigt werden, sind eindeutig und für Menschen wie Maschinen gleichermassen gut aus den Konfigurationsdateien lesbar.

Die oben erwähnten Vorteile von Docs as Code und Diagrams as Code kommen auch hier voll zum Zug. Für DevOps ist Instrastructure as Code gar eine unablässige Grundvoraussetzung. Allgemein gilt, dass sämtliche „Mausklicks“ beim Einrichten von Software (meist bei Dialogfeldern) händisch dokumentiert werden müssen und nicht automatisierbar sind. Wird eine solche (manuelle) Installationsanleitung ausgelassen oder ist sie veraltet – was nach meiner Erfahrung bei diversen IT-Unternehmen eher die Regel als die Ausnahme zu sein scheint – geht wertvolles Know-how verloren, denn der Aufwand, von Null auf den gleichen Software-stand zu rekonstruieren, ist massiv gestiegen, oder eine solche Rekonstruktion ist gar nicht mehr möglich.

Abbildung 4 demonstriert Infrastructure as Code am Beispiel einer docker-compose-Konfigurationsdatei.

Das Beispiel konfiguriert eine einfache, zweiteilige Webanwendung, bestehend aus einem Nginx-Webserver (web) und einer PostgreSQL-Datenbank (db). Der Nginx-Dienst liefert statische Inhalte aus einem lokalen Verzeichnis, das im Container eingebunden ist, und leitet den Port 80 des Hosts auf den Container um, um Zugriff von aussen zu ermöglichen. Der Datenbankdienst nutzt PostgreSQL, initialisiert mit spezifischen Umgebungsvariablen für Datenbank, Benutzer und Passwort, und speichert die Daten persistent in einem Docker-Volume (pgdata). Und keine Angst, Passwörter lassen sich natürlich auch auf sichere Art für Docker hinterlegen, worauf aus Gründen der Leserlichkeit in diesem Artikel allerdings verzichtet wurde.

Drei Zutaten für ausgezeichnete Softwaredokumentation

In meiner Praxis, vielen Recherchen und noch mehr Gesprächen haben sich die folgenden drei Punkte als die Top 3 der erfolgreichsten Zutaten für ausgezeichnete Softwaredokumentation herausgestellt.

1. Docs-as-Code-Infrastruktur mit AuszeichnungsspracheWer sich intensiv mit der unternehmensweiten Verbesserung seiner Dokumentation auseinandersetzt, wird sich je länger je mehr in einem Docs-as-Code-Ansatz wiederfinden. Alle Vor- und Nachteile einer solchen Lösung in die Waagschale geworfen, darf ich – abgesehen von einer anfänglichen Lernkurve – die Verwendung einer vereinfachten Auszeichnungssprache für erfolgreiche (Software-)Dokumentation heute als alternativlos bezeichnen.Als Sprachen-Generator-Kombination empfehle ich in erster Priorität natürlich den Einsatz von AsciiDoc zusammen mit Antora, alternativ von reStructuredText zusammen mit Sphinx. Auf welche Sprache die Wahl auch immer fällt, einzig vom Einsatz von Markdown möchte ich dringend abraten, da es zu viele Dialekte und zu wenig Funktionaliät bietet.Für quellcodenahe Softwaredokumentation haben sich Javadoc für Java, JSDoc für JavaScript etc. etabliert. Auf dieser Flughöhe ist es nicht angebracht, vom Usus abzuweichen.
2. Wenige, aber verantwortliche PersonenDieser Punkt mag überraschen, wird in Unternehmen doch häufig der liberale Jekami-Ansatz propagiert: „Jeder kann mitmachen“. Allerdings tritt dabei fast unweigerlich das Phänomen der Verantwortungsdiffusion auf. Nicht jeder Entwickler kann und will gute Dokumentation schreiben, und aufgrund oft gegensätzlicher Qualitätsansprüche gilt nach meiner Erfahrung hier mehr denn je das altbekannte Sprichwort: „Viele Köche verderben den Brei.“Darum sollte die Arbeit des Dokumentierens auf ein paar wenige Personen konzentriert sein, die das a) gerne und b) gut machen. Nicht jeder sollte einfach Dokumente erstellen und bearbeiten dürfen – und erst recht nicht müssen!Eine Möglichkeit ist die Rolle eines dedizierten „Doctators“ (oder allgemeiner eines „Technical Writers“): Er hat den Überblick über die Dokumentation im Haus, kümmert sich sowohl um die organisatorischen als auch um die technischen Angelegenheiten des Dokumentationsprozesses, unterstützt die Teams beim Dokumentieren und überwacht die Aktualität und Konsistenz der Inhalte.
3. DokumentationsreglementDokumentation darf kein regelfreier Raum sein. Im Gegenteil, sauber strukturierte und organisierte (Software-)Dokumentation stellt das „Gehirn“ des Unternehmens dar. Entsprechende Sorgfalt, Einheitlichkeit und Regelwerke sind daher zwingend. Der GitLab Documentation Style Guide [11] kann uns exemplarisch aufzeigen, was es in Sachen Dokumentation alles zu regeln gäbe. Keine Angst, es muss natürlich nicht gleich derart ausführlich sein, „ehe man zu dokumentieren beginnt“. Aber es ist durchaus angebracht, über die Monate und Jahre ein kontinuierliches Auge auf den Soll- und Istzustand betreffend die Konventionen der hausinternen Dokumentation zu werfen, festgestellte Differenzen zu bereinigen und das diesbezügliche Regelwerk im eigenen Unternehmen stetig zu erweitern.

Fazit

Softwaredokumentation lässt sich lernen. Ausgezeichnete Softwaredokumentation gelingt durch einen ganzheitlichen Ansatz aus a) vereinfachter Auszeichnungssprache, b) Dokumentationsgenerator und c) einfach umsetzbaren organisatorischen Massnahmen, zu denen allen voran einzelne wenige verantwortliche Personen wie ein „Doctator“ oder „Technical Writer“ sowie ein Dokumentationsreglement gehören.

Letzten Endes steht und fällt alles mit systematischem Vorgehen und einer einfach zu verwendenden, akzeptierten und gleichzeitig belastbaren Dokumentationsinfrastruktur. Für die Anfangsphase – oder wer in Sachen Dokumentation gar noch auf einer grünen Wiese steht – kann externe Hilfestellung sehr nützlich sein.

Referenzen

[1] C. Lilienthal, Langlebige Software-Architekturen, 3. Auflage, dpunkt.verlag, 2020
[2] C. Heitzmann, Konsistent und quellcodenah kommunizieren – Javadoc mit Stil, in: JavaSPEKTRUM, 6/2022, SIGS DATACOM, link.simplexacode.ch/ne6c
[3] C. Heitzmann, Dokumentation wie Code behandeln – Auszeichnungssprachen in der Softwaredokumentation, in: IT Spektrum, 4/2023, SIGS DATACOM, link.simplexacode.ch/9h3b
[4] IDW Standard: Grundsätze zur Bewertung immaterieller Vermögenswerte (IDW S 5), 2015
[5] vorliegender Artikel im AsciiDoc-Format, link.simplexacode.ch/36it
[6] Kroki, Examples, kroki.io/examples.html
[7] Spring Security, docs.spring.io/spring-security/
[8] Bonita Documentation, documentation.bonitasoft.com
[9] OptaPlaner, Documentation, www.optaplanner.org/docs/
[10] CIDER, Docs, docs.cider.mx
[11] GitLab, Documentation Style Guide, docs.gitlab.com/ee/development/documentation/styleguide/