Documentation as Code bezeichnet den Ansatz, Architekturdokumentation wie Quellcode zu behandeln: in Textformaten wie Markdown oder AsciiDoc verfassen, per Git versionieren und über Build-Pipelines automatisch als PDF oder HTML ausliefern. Ergänzt durch Continuous Documentation, also iteratives Pflegen im laufenden Entwicklungsprozess, bleibt die Doku aktuell und reviewbar.
Das Wichtigste in Kürze
- Documentation as Code behandelt Architekturdokumentation wie Quellcode: gleiche Werkzeuge, Textformate wie Markdown oder AsciiDoc, versioniert in Git mit Diff-Fähigkeit und Review per Pull-Request.
- AsciiDoc ist für technische Dokumentation die bessere Wahl als Markdown, weil es einen echten Standard bietet, Dokumente modularisieren kann und eine Single Source of Truth ermöglicht.
- Diagramme als Text, etwa mit PlantUML, lassen sich versionieren und direkt vergleichen, scheitern aber bei größeren Architekturdiagrammen, weil das automatische Layout dann nicht mehr kontrollierbar ist.
- Continuous Documentation bindet das Schreiben und Pflegen von Dokumentation in die CI/CD-Pipeline ein, sodass bei jedem Build die Doku mitgebaut und als PDF oder HTML ausgeliefert wird.
- Fehlende Dokumentation fällt im Review-Prozess auf, wenn sie Teil der Definition of Done ist und unvollständige Dokumentation das Mergen eines Pull-Requests blockiert.
Warum Architekturdokumentation so oft liegen bleibt
Architekturdokumentation fällt im Projektalltag regelmäßig hinten runter. Sie wird verschoben, gekürzt oder ganz weggelassen, weil andere Aufgaben dringlicher wirken und Dokumentieren selten Spaß macht.
Die Gründe sind nüchtern und wiederkehrend. Etwas muss schnell fertig werden, also rückt die Doku in der Priorität nach unten. Entwickler programmieren lieber, als Text zu schreiben. Und wer dokumentieren will, braucht oft ein Spezialwerkzeug, etwa ein UML-Tool mit einer Lizenz, die es in der Firma nur einmal gibt und die gerade jemand anderes belegt.
Dazu kommt die Resignation. Viele gehen davon aus, dass die Doku ohnehin niemand liest und dass sie veraltet ist, kaum dass sie geschrieben wurde. Wenn das die Erwartung ist, fängt man gar nicht erst an.
Falk Sippach bezieht diese Beobachtungen auf die Architekturdokumentation, betont aber, dass die Konzepte für andere Dokumentationsarten genauso gelten. Für Tester ist das relevant: Dokumentation ist die Basis, an der sie sich orientieren, ob als Testbasis oder als Nachschlagewerk. Und Tester schauen heute auf vielen Ebenen mit, fordern mal ein Sequenzdiagramm an oder wollen verstehen, wie die Architektur zusammenhängt.
Documentation as Code: Doku wird behandelt wie Quellcode
Der Kerngedanke lautet, Dokumentation wie Source Code zu behandeln. Dieselben Werkzeuge, dieselben Textformate, dieselbe Versionsverwaltung, dieselbe Integration in den Build.
Der Ansatz ist nicht neu, und viele praktizieren ihn, ohne ihn so zu nennen. Das Suffix “as Code” ist mittlerweile breit im Einsatz, von Infrastructure as Code bis Diagrams as Code. Die Idee dahinter bleibt konstant: Dinge im Code abbilden oder sie zumindest so handhaben wie Code.
Konkret heißt das, du schreibst die Doku in derselben IDE neben dem Quellcode, in einer Textdatei mit einem leichtgewichtigen Format wie Markdown oder AsciiDoc. Du brauchst kein Extra-Tool, keine Lizenz, keinen Kontextwechsel. Editor, Kommandozeile und Build-Werkzeug sind schon da.
Geschrieben wird einfach hintereinander weg, ähnlich wie bei einem Brief. Überschriften, Aufzählungen, Tabellen markierst du mit leichten Auszeichnungen. Du siehst zunächst nicht das fertige Layout, aber es schreibt sich leichter. IDE-Plugins liefern eine Vorschau: links der Text, rechts das gerenderte Ergebnis.
Wenn ich das Konzept vorstelle, kennen es viele schon. Und wer es nicht kennt, merkt sehr schnell: Das ist ja total einfach, warum machen wir das nicht einfach so.
— Falk Sippach
Warum AsciiDoc gegenüber Markdown im Vorteil ist
Für technische Dokumentation ist AsciiDoc die robustere Wahl, weil Markdown nur ein dünner Standard mit vielen herstellerabhängigen Ausprägungen ist.
Markdown funktioniert für vieles, aber sobald es um technische Doku geht, fehlen Funktionen oder sie existieren nur über Dialekte. AsciiDoc bringt diese Funktionen direkt mit, etwa ein Table of Content und saubere Tabellen.
Ein praktischer Vorteil ist die Modularisierung. Statt einer großen Datei legst du zehn kleine an, jede für ein Kapitel oder einen Abschnitt. Ein zentrales Dokument inkludiert diese Teile. So stellst du dir Inhalte flexibel zusammen und behältst trotzdem eine Single Source of Truth.
Der Vorteil von Plain Text: Fokus auf den Inhalt
Textformate lenken nicht ab. Du schreibst Inhalt, nicht Formatierung.
In Word beschäftigt man sich mit hundert Nebensachen, und das Layout sieht am Ende oft anders aus als gedacht. Word ist für Briefe gemacht, nicht für große Dokumente. Wer im Studium eine längere Arbeit darin geschrieben hat, kennt das.
Beim Schreiben einer E-Mail denkt auch niemand über Formatierung nach. Genau dieses Gefühl stellt sich bei Markdown und AsciiDoc ein. Der Inhalt steht im Vordergrund, das Drumherum tritt zurück.
Git macht Doku versionierbar und reviewbar
Dokumentation gehört in dieselbe Versionsverwaltung wie der Code, und Git ist dafür heute der Standard.
Git ist ein verteiltes System. Mit einer lokalen Kopie arbeitest du offline weiter, etwa im Zug, und pushst die Änderungen später zurück. Du kannst mergen, Pull Requests stellen und Reviews durchführen, für Code wie für Dokumentation.
Damit entsteht echte Nachverfolgbarkeit. Du vergleichst Stände, siehst Unterschiede und arbeitest Feedback nachvollziehbar ein. Genau an dieser Stelle geht Documentation as Code fließend in Continuous Documentation über.
Drei Stufen, um Diagramme einzubinden
Ein Bild sagt mehr als tausend Worte, und ein Dokument mit dreißig Seiten und vielen Grafiken wird eher gelesen als hundert reine Textseiten. Für Diagramme gibt es drei Stufen, die sich in Flexibilität und Pflegeaufwand unterscheiden.
Die Stufen im Überblick:
| Stufe | Was | Problem beim Feedback |
|---|---|---|
| 1 | Binärformate wie PNG, JPEG | Diagramm muss im Originalprogramm geöffnet, geändert und neu exportiert werden |
| 2 | Vektorgrafik-Tools wie Visio oder UML-Werkzeuge | Eigenes Format, zusätzlicher Export nach PNG oder JPEG nötig |
| 3 | Textbasierte Diagramme (Diagrams as Code) | Kaum, da die Quelle Text ist und versionierbar bleibt |
Bei den ersten beiden Stufen entsteht bei jeder Änderung ein zusätzlicher Schritt. Du öffnest ein anderes Programm, änderst das Diagramm und exportierst es erneut. Das kostet bei jeder Feedback-Schleife Aufwand.
Der Trick mit Draw.io
Ein guter Kompromiss für komplexere Grafiken ist Draw.io, auch bekannt als Diagrams.net, ein leichtgewichtiges Open-Source-Vektorgrafikprogramm. Es läuft standalone, als Plugin in Confluence und in IDEs, also genau dort, wo du es brauchst.
Der eigentliche Kniff steckt in den Metadaten. Draw.io speichert seine Vektordaten direkt im PNG- oder JPEG-Bild ab, vergleichbar mit Exif-Daten einer Kamera. Du referenzierst das Bild ganz normal und kannst es trotzdem jederzeit wieder öffnen und bearbeiten. Der separate Exportschritt entfällt. Für Architekturdiagramme mit vielen Boxen und Linien ist das eine praktikable Lösung.
Diagramme als Text mit PlantUML
Auf der dritten Stufe schreibst du Diagramme als Text, mit Werkzeugen wie PlantUML. In einer festen Notation entstehen Sequenz- oder Komponentendiagramme, und das Tool rendert das Layout selbst.
Bei Sequenzdiagrammen klappt das gut, weil die Richtung klar ist, von oben nach unten und von links nach rechts. Bei Komponentendiagrammen wird das Layout bei jedem Rendern etwas anders, und mit zunehmender Größe stößt der Ansatz an Grenzen. Dann ist der Draw.io-Mittelweg besser.
Der textbasierte Ansatz hat einen klaren Reiz: Es bleiben Textdateien, die ins Git wandern, sich versionieren und mit früheren Ständen vergleichen lassen. Oft reicht schon der Text, um den aktuellen Stand zu erfassen, ganz ohne das gerenderte Bild.
Beschränkung als Nebeneffekt: kleinere, gezieltere Diagramme
Dass textbasierte Diagramm-Renderer bei großen Strukturen an Grenzen stoßen, ist kein reiner Nachteil. Es zwingt zur Abstraktion.
Das eigentliche Problem ist generell, dass Diagramme zu groß werden. Man will alles hineinpacken, und genau dann ist die Grafik veraltet, bevor sie gespeichert ist. Eine Beschränkung auf das Wichtige drängt dazu, mehrere kleinere Sichten zu erstellen statt einer Tapete im A0-Format.
Wie Continuous Documentation in die Pipeline kommt
Continuous Documentation bedeutet, dass die Doku Teil von Build und Auslieferung wird, genau wie der Code.
Im einfachsten Fall hast du eine AsciiDoc- oder Markdown-Datei. Prozessoren erzeugen daraus PDF oder HTML, auf der Kommandozeile oder über Plugins. Da Build-Werkzeuge ohnehin gescriptet sind, Software bauen, Tests ausführen, Container erstellen, kommt ein Schritt für die Doku einfach dazu.
Das Ergebnis wird abgelegt, als PDF, als Webseite oder per Export ins firmenweite Wiki wie Confluence. Plattformen wie GitHub und GitLab rendern Markdown und AsciiDoc ohnehin direkt im Browser, sodass du immer das Endergebnis siehst.
Die Doku läuft mit der Software mit. Baust du Version 7.3, entsteht die Doku in Version 7.3 und liegt dort. Version 7.2 bleibt in einem anderen Verzeichnis erreichbar. Du kommst jederzeit an jeden Stand.
Reviews machen fehlende Doku sichtbar
Ein Review-Prozess sorgt dafür, dass Dokumentation nicht vergessen wird. Sie wird Teil der Definition of Done.
Implementiert ein Entwickler ein Feature mit Auswirkung auf die Architektur, gehört die Dokumentation zur Erledigung dazu. Im Review fällt auf, wenn der Code angepasst und getestet, die Doku aber nicht aktualisiert wurde. Dann wird nicht gemergt, und es geht noch einmal zurück.
Genau hier zahlt das Textformat ein. Im Pull Request siehst du den Diff der Doku direkt, so wie beim Code. Bei Tools mit eigenem Binärformat fehlt dieser Diff, und das Review wird schwerer.
Generieren ja, aber nur wo der Code es nicht hergibt
Dokumentation aus dem Quellcode zu generieren lohnt sich dort, wo Informationen sonst nicht sichtbar werden, nicht für das, was im Code ohnehin steht.
Was im Quellcode direkt lesbar ist, sollte nicht redundant in der Doku landen, auch nicht generiert. Liest niemand. Dokumentation muss schlank bleiben, damit die Akzeptanz stimmt.
Softwarearchitektur dagegen steckt nicht offensichtlich im Code. Sie ist das große Ganze, das alles zusammenhält, und genau das sieht man zunächst nicht. Hier wird Generieren wertvoll. Mit Metainformationen im Code lassen sich Domain-Driven-Design-Elemente wie Bounded Context, Aggregates oder Value Objects markieren und daraus Diagramme erzeugen. Ändert sich der Code, ändert sich das Diagramm sofort mit.
Ein fertiges Standardwerkzeug dafür ist kaum verbreitet; manche Branchen mit konkretem Bedarf bauen sich etwas Eigenes. Schwer ist das nicht. Du kannst einen automatisierten Test schreiben, der auf den Quellcode zugreift, Informationen herausholt und daraus eine PlantUML- oder AsciiDoc-Datei erzeugt, die anschließend in der Doku gerendert wird.
