Falk Sippach
16.11.2021
Beim Architektur-Punsch 2021 hält Stephan Pirnbaum einen Vortrag: 'Softwaredokumentation - Liebe auf den zweiten Blick'. Ich habe mich dazu mit ihm unterhalten.
Stephan Pirnbaum wird in Kürze bei unserem Architektur-Punsch am 13.12.2021 dabei sein und ich habe mit ihm über seinen Vortrag “Softwaredokumentation - Liebe auf den zweiten Blick” gesprochen. Im Folgenden erwartet Euch ein Videomitschnitt zu unserem Austausch. Alternativ könnt Ihr die wichtigsten Aussagen auch direkt in diesem Blog nachlesen.
(Falk) “Hallo Stephan, stell Dich bitte kurz vor."
Stephan: “Ich bin Consultant bei der BUSCHMAIS GbR, das ist ein Beratungsunternehmen aus Dresden. Wir machen viel im Bereich Architekturberatung, -modernisierung und -absicherung, insbesondere mit dem Tool jQAssistant. Das ist ein Opensource-Tool, welches auch in meinem Vortrag vorkommen wird und hinter welchem wir federführend stehen. Mein Fokus liegt auf der Redokumentation, Modernisierung und dem Aufräumen von Software-Systemen.”
“Software- und Architekturdokumentation wird in vielen Projekten stiefmütterlich behandelt. Warum ist das so?"
Stephan: “Das ganze hat zwei Seiten. Auf der Seite des Entwicklers ist Softwaredokumentation jetzt nicht das spannendste Thema. Man schafft nichts, was am Ende beim Kunden läuft und Daten verarbeitet. Es stellt sich die Frage: Was dokumentiere ich überhaupt? Warum dokumentiere ich und liest das überhaupt jemand? Lass uns doch stattdessen lieber das Feature entwickeln! Weil - und das ist die andere Seite - der Product Owner setzt hier den Fokus: Features sind wichtiger als Dokumentation. Dieser Ansatz ist jedoch sehr schade. Schließlich ist so ein Softwareprojekt sehr aufwändig und kostet viel Mühe und Zeit. Das möchte man konservieren, um auch neue Teammitglieder effizient aufzugleisen - an der Stelle ist Dokumentation einfach unerlässlich.”
“Was sind aus Deiner Sicht wichtige Gründe, warum wir in unseren Projekten der Dokumentation einen größeren Stellenwert einräumen sollten?"
Stephan: “Zum einen das Festhalten von Wissen, sowohl auf der fachlichen als auch technischen Seite. Das ist insbesondere im Rahmen von Architekturentscheidungen wichtig - also warum haben wir uns dafür entschieden, bestimmte Technologien oder Muster einzusetzen? Solche Entscheidungen sind später nicht mehr nachvollziehbar. Ohne Dokumentation ist es schwierig, neue Entwickler in das Projekt zu integrieren. Gleichzeitig ist es wichtig, dass das Wissen nicht nur in den Köpfen der Beteiligten steckt, um einen Wissensverlust über die Zeit zu vermeiden wenn z. B. jemand das Projekt verlässt. Neben all dem ist Dokumentation ein sehr gutes Mittel zur Kommunikation und unterstützt im Team eine gemeinsame Basis zu schaffen, so dass alle über das Gleiche reden bzw. das gleiche Verständnis haben.”
“Welche Ideen bringst Du zu unserem Architektur-Punsch mit, die bei Entwicklungs-Teams mehr Enthusiasmus zum Thema Dokumentation entfachen können?"
Stephan: “Mein Ziel ist es, Dokumentation wieder spannend und weniger mühselig machen. Das fängt bereits mit dem Format an, in dem man dokumentiert. Word oder Powerpoint sind da relativ ungeeignet. Sie sind schwerfällig, weit weg vom Code und schlecht wartbar oder zu pflegen. Mein Tipp wäre - probiert so ewtas wie Markdown oder AsciiDoc einfach mal aus und verwaltet Eure Dokumentation direkt mit dem Sourcecode. Dadurch ist sie versionsverwaltet, nachvollziehbar und für die Entwickler schneller erreichbar. Das motiviert bspw. die Dokumentation bei Schwachstellen aktuell zu halten. Die Frage ist: Wie mache ich diese Dokumentation verfügbar? Ich kann durch Maven usw. im Buildprozess Dokumente generieren und allen Projektbeteiligten zur Verfügung stellen. Spannend ist wie kann ich Documentation-Code-Gap (also die Diskrepanz zwischen dem Dokumentierten und dem Implementierten) minimieren? Die Dokumentation bringt schließlich nichts wenn sie nicht zum Code passt. Da hilft jQAssistant, um Strukturen im Code zu analysieren und auch Dokumentation zu generieren. Und in der anderen Richtung kann ich auch Strukturen so dokumentieren, dass ich sie anschließend mit jQAssistant gegen die Implementierung prüfen kann. So kann ich beispielsweise mit dem ContextMapper-Werkzeug die Bounded Contexts aus dem Domain Driven Design textuell festhalten, als Dokumentation rendern und gegen den Code halten. Auf diese Weise kann ich Dokumentation aus Modellen generieren und sogar die Umsetzung validieren. Das minimiert die Documentation-Code-Gap. In Summe macht es das für Entwickler spannender, weil das Tooling nicht so trocken ist und näher an die Entwicklung heranrückt.”
“Wie sollte Dokumentation aus Deiner Sicht in den Lebenszyklus von Software-Projekten eingebettet sein?"
Stephan: “Der wichtigste Punkt ist - fangt so zeitig wie möglich damit an! Baut Euch besonders bei ‘Grüne-Wiese-Projekten’ von Beginn an Eure Toolchain auf. Nutzt vorhandene Best Practices oder Templates, wie z. B. arc42 oder Architecture Decision Records, so wisst ihr was, wo und wie man bestimmte Themen dokumentieren kann. Bei bestehenden (Legacy) Projekten, die noch viele Jahre fortgesetzt werden, sollte man die bestehende Dokumentation auch immer wieder auf den Prüfstand stellen und aktualisieren oder bei Bedarf erneuern und in eine passendere Struktur transformieren. Die Entwickler sollten motiviert werden, z. B. durch das Vereinfachen der Prozesse zur Dokumentationserstellung. Das führt auch dazu, dass die Dokumentation auf breitere Füße gestellt wird und nicht allein zum Aufgabengebiet der Architektengilde gehört.”
“Das klingt alles sehr spannend. Vielen Dank, dass Du Dir die Zeit für das Interview genommen hast! Ich freue mich schon auf Deinen Vortrag auf dem Architektur-Punsch!!"
Mehr Anregungen könnt Ihr am 13. Dezember 2021 bei unserem Architektur-Punsch bekommen. Einfach anmelden! Neben dem Vortrag von Stephan Pirnbaum gibt es noch einige weitere spannende Programmpunkte dort zu entdecken. Save the date…