Hallo und herzlich willkommen zu einer neuen Folge vom Podcast Software Testing. Ich bin euer Host Ritschi und sende hier live von der OOP 2024 aus München. Bei mir zu Gast Falk Sippach, mit dem ich über Architekturdokumentation gesprochen habe und wie diese leichtgewichtig erstellt werden kann. Und wir Tester wissen ja, wie wichtig Dokumentation ist, ob als Testbasis, Nachschlagewerk oder sonst etwas. Ich glaube hier steckt eine oder andere Inspiration auch
drinnen, wie wir vielleicht auch mit unserer Testdokumentation umgehen können. Ich würde mich auf jeden Fall freuen, wenn ich auch euer Feedback dazu erhalte an podcast@software-testing.fm Und wenn euch dieser Podcast gefällt, dann lasst gerne ein Like oder eine Bewertung auf YouTube, Apple oder Spotify da. Viel Spaß bei der Folge. Hallo Falk, schön, dass du da bist. Hallo Richard, schön, dass ich hier sein darf.
Ja, ich freue mich sehr. Wir sind ja hier auf der OOP 2024 in München. Der dritte Tag, so es geht schon langsam so, gleitet das schon aus. Noch ein bisschen Programm heute und morgen, aber es wird schon weniger. Und ich merke jetzt auch schon bei mir den Energielevel, der muss ich schon reingeben. Aber wir werden jetzt hier eine schöne Zeit haben auf jeden Fall. Ich
habe im Vorfeld ja deinen Abstract gelesen und dein Thema mir auch angeschaut. Und das ist für mich als Tester total spannend, weil es geht um Dokumentation, um Architekturdokumentation. Und Dokumentation ist ja für uns Tester oder Qualitätsmenschen ja immer so die Basis dann auch, mit der man irgendwas machen kann, wo man so nachschauen kann und deswegen auch unfassbar
wichtig. Und deswegen freue ich mich, dass wir hier auch mal ein bisschen darüber sprechen können, weil du versprichst da also ein bisschen eine Leichtgewichtige oder hast einen Ansatz für eine leichtgewichtigere Dokumentation, wenn ich es richtig verstanden habe. Aber da kommen wir wahrscheinlich auch gleich hin. Ja, ich sehe immer das Problem, dass Dokumentation gerne hinten runterfällt. Testen mag das anders sein, da habe ich jetzt keine Erfahrung, aber im Architekturbereich
ist es etwas, was man ganz gerne auch einfach mal weglässt. Und da wollte ich heute mit den Ideen quasi so Ansätze zeigen, die es leichter machen zu dokumentieren, so dass es dann vielleicht doch nicht wegfällt. Das ist so ein bisschen der Hintergrund. Vielleicht bleiben wir da noch kurz beim Problem. Warum passiert es denn nicht, dass es gut läuft? Was ist denn so das Hindernis?
Ja, es ist ganz viele verschiedene Sachen. Eines ist immer, dass die Priorisierung anders ist, dass schnell irgendwas fertig werden muss und dann ist es für mich halt nicht so wichtig, dass es nicht so viel Spaß macht, dass man nicht so gerne Dokumentation schreibt und lieber irgendwie was programmiert, jetzt die Entwickler zum Beispiel. Dann natürlich, dass die Tools vielleicht auch nicht die gleichen sind, die man so tagtäglich braucht und dann muss man irgendwie wechseln,
muss vielleicht eine Lizenz braucht man, um ein spezielles UML-Werkzeug zu nutzen. Lizenz gibt es aber nur einmal in der Firma, der ist gerade im Gebrauch und all solche Sachen. Und ich habe heute mal eine Umfrage gemacht, ich hatte anderthalb Stunden, dann habe ich es interaktiv gemacht, habe ich so eine Mentimeter-Umfrage und da haben dann auch ganz viele Leute quasi so ihre Gründe rein. Es geht so in die Richtung, was ich auch schon sagte, dass es zu kompliziert ist, zu viel
Aufwand, zu viel oder zu wenig. Genau, das ist auch ein Thema, dass viele denken, das liest ja am Ende auch keiner. Dann ist es sowieso wieder veraltet, sobald es geschrieben ist. Das sind auch so Themen, dass man dann denkt, da brauche ich gar nicht anfangen. Da denkt keiner an uns Tester. Ja, ich weiß gar nicht. Also ich beziehe mich wirklich auf die Architektur-Dokumentation und die ist jetzt glaube ich für die Tester erstmal jetzt nicht so relevant, aber die
Konzepte sind auch für andere Arten von Dokumentation natürlich genauso gültig. Ich habe halt nur so einen Fokus darauf, weil es auch um Diagramme geht, die ich erstelle, da passt es besser. Ich finde es ja schon immer schön, weil Testen passiert ja auf vielen Ebenen und heute ist das Tester ja nicht nur mehr im Abnahmetest, sondern einfach auch überall im Prozess mit drin und schaut mal hier und da, möchte mal ein Sequenzdiagramm sehen oder wie hängt die Architektur
zusammen oder wie sind so die Dinge beschrieben. So gesehen ist es immer ein gutes Nachschlag. Ja, genau. Okay, also viele Gründe, warum man es nicht ordentlich macht. Ich meine, ich kenne das auch aus leidvoller Erfahrung. Daher bin ich auch schon froh, wenn überhaupt was da ist und dann im zweiten Schritt froh, wenn es halbwegs aktuell ist. Also da sind sehr häufig dann schon so die Hemmschuhe dabei. Ja und welchen Ansatz hast du denn jetzt auch
auch da mit im Gepäck für uns? Also man kann es eigentlich in ein paar Worten zusammenfassen. Ich nenne den Ansatz, oder ist nicht von mir erfunden, ich habe das mal vor ein paar Jahren entdeckt und das machen viele, manche nennen es vielleicht nicht so, aber man kann es gut
zusammenfassen als Documentation as Code und als Continuous Documentation. Und das Documentation as Code ist die Idee, dass wir die Dokumentation wie Source Code behandeln, also die selben Werkzeuge nutzen können, Textformate, leichtgewichtige Sachen nutzen, das Ganze auch in Bildprozesse integrieren, automatisieren können, vielleicht auch mal Sachen generieren, um nicht so Redundanzen zu haben und solche Sachen. Das ist so dieser eine Ansatz. Dieses as Code ist ja ein bisschen
überschrapaziert. Es gibt ja auch Infrastructure as Code und Diagrams as Code, also das sieht man öfter. Aber die Ideen sind mal sehr ähnlich, dass man Sachen im Code abbildet oder ähnlich wie Code behandelt und von daher passt das so in diesen Zeitgeist gerade, finde ich.
Und dieses Continuous Documentation versucht dann nochmal so diese iterativ-inkrementellen Prozesse, nachdem wir heute ja immer mehr arbeiten, agil arbeiten, dann auch die Dokuarbeit, das Schreiben der Doku, das Pflegen der Doku, damit reinzubringen, sodass es eben nicht nur einmal gebaut ist und dann vergesst man es und veraltet, sondern dass es quasi immer weiter auch gepflegt wird, Feedback eingesammelt wird und das dann so ein iteratives, inkrementelles
Vorgehen ist. Und das passt auch wieder sehr gut zu diesem Continuous-Begriff. Da gibt's ja in der Softwareentwicklung Continuous Integration, Continuous Delivery. Das ist ja auch genau das easy Idee, dass die Software kontinuierlich integriert und ausgeliefert wird und die Doku soll jetzt eben auch kontinuierlich integriert und ausgeliefert werden. Und da kommt das her. Wie kann ich mir denn diese zwei Schritte, ich würde es jetzt vielleicht gesondert mal
anschauen, in der Praxis dann wirklich, wirklich vorstellen? Wie implementiert man das? Total einfach. Das ist auch gerade das, was die Entwickler so lieben. Man hat keine extra Tools, weil man hat sowieso seinen Texteditor, seine IDE, man hat seine Kommandozeile, man
hat sein Bildwerkzeug, was ja schon da ist, was man ein bisschen erweitern muss. Und man schreibt einfach in demselben Werkzeug, in der IDE, Entwicklungsumgebung, eine andere Textdatei neben dem Sourcecode, die halt dann ASCII-Doc oder Markdown zum Beispiel, so Textformate, weiß ein bisschen anders und kann da quasi sehr einfach, so wie wenn man einen Brief schreibt, einfach hintereinander weg Sachen schreiben. Hat so ein bisschen leichte Auszeichnungsmöglichkeiten,
Überschriften, Bullet-Point-Listen und so weiter. Kann auch Tabellen machen und so. Und das schreibt sich, also jeder, der vielleicht mal im Studium oder in einer Schule mal eine große Wörterdatei, eine Arbeit in Word schreiben muss, der weiß, das macht keinen Spaß. Word ist nicht dafür gemacht, dass man große Sachen schreibt. Ein Brief ist prima, aber Word ist halt so das Standard Textverarbeitungsprogramm oder ähnliche. Ist erstmal egal, diese Visivic-Tools.
Und der Ansatz ist jetzt anders, weil wir ja erstmal nicht sehen, wie das Endergebnis aussieht, aber es schreibt sich eben viel leichter und man hat dann in so einer IDE, gibt es dann Plugins, wo man Preview sich anschauen kann, dann sieht man rechts quasi, wie dann das Ergebnis aussieht, links schreibt man. Also es fühlt sich irgendwie sehr natürlich
an und das lieben die meisten Entwickler. Also wenn ich das Konzept vorstelle, viele kennen es eh schon, weil wenn ich das mal irgendwie vorstelle und es hat jemand auch nicht gehört, dann merkt man sehr schnell, ja, das ist ja total einfach, warum machen
wir das nicht einfach so. Und gerade auch im Softwareentwicklungsbereich gibt es ja so viele Plattformen, GitHub, GitLab und solche Sachen, die haben dann auch immer schon eine Integration mit, dass wenn man dort Dateien hat in Markdown oder Asciidog, werden die immer gleich gerendert. Das heißt, man sieht auch immer das Endergebnis im Browser und so weiter. Also es ist einfach gut integriert und sehr einfach gehalten.
Das finde ich total schön, weil ich nutze selbst Markdown mit meiner Notizverwaltung und was ich da auch total dran schätze, ist so distraction-free irgendwo. Also im Word habe ich tausend Sachen, mit denen ich mich beschäftigen kann, von Formatier kann ich hier rein schieben, dann schaut das immer irgendwie anders aus, als ich mir das nochmal
vorgestellt habe. Aber hier ist es quasi einfach nur plain Text, den ich schreibe und ich kann mich auf den Inhalt fokussieren und nicht auf das Drumherum. Einfach einen Brief schreiben, E-Mail schreiben, da denkt man ja auch nicht über Formatierung
nach normalerweise, so schreibt man das. Und was dann auch noch dazu kommt, Markdown kann das nicht ganz so gut, weil Markdown ist kein Standard in dem Sinne oder es ist ein sehr dünner Standard und dann gibt es verschiedene Ausprägungen von verschiedenen Herstellern. Da ist dann Asciidoc tatsächlich aus meiner Sicht die beste Wahl. Die bringen noch so ein paar Zusatzfunktionen mit, die gerade für technische Dokumentationen sehr wichtig
sind, sowas wie Table of Content, dass man Tabellen einbauen kann. Also Markdown kann das tatsächlich auch, aber eben nur über irgendwelche Dialekte, die dann noch dazu kommen. Und was da zum Beispiel sehr spannend ist, gerade in Asciidoc, dass man seine Dokumente auch modularisieren kann. Das heißt, man hat nicht eine große Datei, sondern hat irgendwie zehn Dateien, die immer so ein Kapitel, einen Abschnitt enthalten. Man hat dann ein zentrales
Dokument oder hat auch mehrere, die dann einzelne von diesen zehn inkludieren. Und dann kann man sich auch inhaltlich sehr schön Sachen zusammenstellen, obwohl man eine Single Source of Truth sozusagen hat. Das finde ich auch einen wichtigen Aspekt. Das finde ich auch super, weil das ist natürlich dann auch plus die Modularisierung auch die Nachverfolgbarkeit, wenn sich was ändert. Natürlich dann auch jetzt, wenn es ein Git oder sonst irgendwas wahrscheinlich einfacher gestaltet.
Git ist nochmal ein guter Stichwort, das habe ich noch gar nicht gesagt. Das Docs.is.Code hat dann noch die Idee, wir wollen es zum Code bringen, in die Nähe des Codes. Und wir wollen es vor allem auch versionieren. In einer Versionsverwaltung geht es dann der Standard heutzutage. Git hat den Vorteil, es ist ein verteiltes Versionsverwaltungssystem. Das heißt, ich kann sogar Offline-Fähigkeiten, wenn ich eine lokale Kopie habe, wenn ich im Zug sitze,
kann ich weiterarbeiten. Wenn ich wieder auf Arbeit oder im Büro bin, kann ich es wieder pushen und dann kann ich es wieder merchen, kann Pull-Requests machen, habe so Code-Review möglich oder auch Dokumentations-Review-Möglichkeiten. Da gehen wir jetzt schon in diesen Continuous Documentation Teil rein. Also es geht zueinander über Hand in Hand quasi. Bleiben wir noch mal kurz bei den Dokumenten. So eine Dokumentation lebt ja dann auch von
Bildern, Diagrammen, die ein bisschen was visualisieren oder so. Wie kann man denn das integrieren? Genau, da gibt es das schöne Sprichwort "Ein Bild sagt mehr als tausend Worte". Und das ist sicher auch ein Problem, wenn man nochmal an die Probleme denkt von eben. Wenn ich da so ein Dokument mit 100 Textseiten habe, das liest dann auch keiner. Wenn ich aber ein Dokument mit 30 Seiten habe und vielen Grafiken und da drin immer eine kurze Beschreibung,
das ist sehr gut. Also von daher brauchen wir auf jeden Fall. Und das geht relativ einfach. Da gibt es natürlich viele Optionen. Ich habe es heute in meinem Vortrag mal "Evolution der Diagrammarten" genannt. Und die erste Stufe ist so klassisch binär Formate, PNG, JPEG. Die kann man immer irgendwie erstellen, wie auch immer. Und dann hat man die und dann referenziert man sie oder fettet sie ein in Word, wie auch immer. Problem ist natürlich,
wie kriege ich Feedback? Also das Feedback wieder eingearbeitet. Ich muss das Diagramm nochmal anfassen. Dann muss ich halt das Programm aufmachen, wo ich es das letzte Mal bearbeitet habe. Das hat irgendein spezielles Format und kann ich da was ändern. Exportiere es wieder. Ist nicht so einfach. Der nächste Schritt wäre tatsächlich auch noch sehr, also es ist ja jetzt sehr flexibel, Pixelgrafikformate. Das kann man alles machen. Der nächste Schritt
wären Vektorgrafikprogramme. Da gibt es dann so klassische wie Visio oder ich zähle jetzt auch mal sowas wie UML-Werkzeuge dazu, die auch mehr, das sind keine Vektorgrafikprogramme, aber auch so in die Richtung gehen, wo ich dann quasi ein gezieltes Format habe, wo ich dann auch die Strukturelemente von UML, Notationselemente zum Beispiel nutzen kann und am Ende das als Vektordatei gespeichert wird, sodass ich es dann auch vergrößern, verkleinern kann und
so weiter, verlustfrei. Aber auch da muss ich, damit ich es einfach so irgendwo einbetten kann oder in einer Webseite referenzieren kann, muss ich es wieder als einen PNG oder JPEG wieder exportieren. Also ich habe immer einen extra Schritt, wenn ich dann wieder die Feedbackschleife gehe, will was ändern, will was hinzufügen, dann ist immer mehr
Aufwand. Da gibt es aber einen sehr schönen Trick, sind auch bei der Stufe 2 gerade, und zwar gibt es eine Software, die nennt sich DrawIO oder Diagrams.net, das ist so ein leichtgewichtiges Open Source, behaupte ich immer, ich hoffe, das stimmt, Vektorgrafikprogramm. Das hat zum Beispiel den Vorteil, das läuft standalone, ist eine JavaScript-Anwendung, TypeScript-Anwendung, Elektron oder es läuft aber auch in Confluence sieht man das ganz oft als Plugin zum Beispiel,
im Wiki oder es läuft auch in IDEs in Plugins. Das heißt, das habe ich immer genau da, wo ich es brauche, ich muss da nicht irgendwo wechseln, das ist schon mal ein großer Vorteil. Aber es hat noch eine andere tolle Funktion, die können, das ist nicht neu, das haben die nicht erfunden, in den Binärformaten JPEG, PNG und so weiter gibt es Metadaten. Kameras nutzen das, um Exif-Daten zum Beispiel zu speichern und die nutzen das, um da ihre Vektordatei
in das JPEG mit reinzuspeichern oder PNG. Und dann habe ich quasi ein PNG, was ich ganz normal abspeichere, wo dann die Metadaten mit drin sind, sodass ich es wieder öffnen kann, um es weiter zu bearbeiten und gleichzeitig kann ich es aber ganz normal referenzieren und immer benutzen. Da habe ich schon mal diesen Schritt, ich brauche ein anderes Tool, muss wieder exportieren, fällt schon mal weg. Und das ist dann, finde ich, ein ganz
guter Kompromiss für komplexere Grafiken. Wenn man dann so Architektur-Diagramme, wo man, sage ich mal, Dutzende von irgendwelchen Boxen und Linien hat, da wird dann schon recht groß, da funktioniert das, finde ich, ganz gut und ist ein schöner Kompromiss. Und der dritte Schritt wäre aber, dass man auch die Diagramme als Text schreibt. Wir haben jetzt schon Markdown und ASCII-Doc als leichtgewichtige Textformate kennengelernt, die ja nur aus
Tizen-Sprachen sind. Und das gibt es auch für Diagrammenarten. Das bekannteste in meinem Feld ist PlantML oder PlantML. Und da kann man auch in so einer bestimmten Notation ohne Ablenkung quasi einfach hintereinander weg Sequenzdiagramme, Komponentendiagramme erstellen. Und der rendert das dann aber natürlich so, wie es passt. Bei Sequenzdiagrammen ist das relativ gut, weil da ist relativ klar von oben nach unten, von links nach rechts. Bei
Komponentendiagrammen ist dann bei jedem mal ein bisschen anders. Da ist es ein bisschen schwieriger, wenn es größer wird, weil man dann nicht genau das Layout hinbekommt, was man sich vielleicht wünscht. Und wenn es größer wird, funktioniert das auch nicht mehr gut. Da müsste man dann diesen Mittelweg gehen. Aber ansonsten finde ich gerade diesen textbasierten Ansatz, nennt sich dann auch Diagrams as Code, finde ich einfach super,
weil man weiter Textdateien hat. Die kann man wieder ins Git schmeißen, kann versionieren, kann sie vergleichen mit vorherigen Ständen. Ist eigentlich perfekt und es ist auch gut lesbar. Man sieht den Text und braucht das Diagramm eigentlich gar nicht, wenn man mal kurz guckt, wie jetzt der Stand ist. Man kann sich das ja immer anschauen, weil man kriegt das auch im Quellcode sozusagen raus. Ja, ich finde vor allem, da kann ich mir gut vorstellen,
die Vergleichbarkeit auch zu alten Versionen. Wenn ich nur binär dateien habe, ist es ein bisschen schwierig, muss ich mal gucken. Geht auch, aber ist nicht so schön. Genau. Und was ich auch noch, vielleicht ist es ja auch sogar ganz gut, wenn es nicht zu groß werden kann. Also, du sagst, diese Renderer können nur eher mit dem kleineren Set, dass man da nicht wieder anfängt, solche Tapeten zu machen, die dann so auf A0 irgendwo...
Das ist, glaube ich, ein grundsätzliches Problem, was ich jetzt gar nicht groß angesprochen habe, weil das kann man nicht so jetzt mit der Idee lösen, wie ich habe. Aber da hast du vollkommen recht. Wir müssen uns eigentlich beschränken auf die wichtigen Sachen, müssen abstrahieren. Das fällt uns schwer, deswegen machen wir es immer größer und ist alles drin, aber es ist schon wieder veraltet, wenn es noch nicht mal richtig gespeichert ist.
Von daher zwingt uns das dann auch dazu, vielleicht kleinere Sachen zu machen und nähere Sachen verschiedener Sichten vielleicht auch zu haben. Ist ja eigentlich ein guter Punkt. Wenn wir jetzt so in die Richtung des Prozesses gehen, also so Continuous Documentation, wie man das genannt, wie integriere ich das in meine Prozesse, damit ich das auch jetzt auch nicht vergesse vielleicht oder auch immer wieder drauf gestupst werde?
Genau. Am Ende machen wir den einfachsten Fall. Wir haben einen ASCII-Doc oder einen Markdown-Datei, da gibt es Prozessoren, die diesen Quellcode nehmen, diese Austeilungssprache und daraus ein PDF erzeugen, HTML erzeugen. Und das kann ich auf der Gwando-Zeile ausführen, da gibt es Werkzeuge, ich kann das in viele Bildwerkzeuge, gibt es Plugins, integrieren. Und meine Bildwerkzeuge sind ja eh gescriptet. Die bauen meine Software, die führen die Tests aus, die automatisierten,
die bauen Docker-Container, schieben das irgendwo auf ein Testsystem. Und da kann ich natürlich wunderbar einfach sagen, das soll jetzt neben der Source-Code, den er kompiliert, auch noch den Dokumentationen übersetzen, wie auch immer das dann transpillieren, glaube ich, sagt man das dann. Und dann wird es irgendwo abgelegt als PDF oder als Webseite oder es kann sogar nach Confluence exportiert werden, weil Confluence ist ja, oder Confluence als
das Wiki, was man häufig antrifft, aber kann auch ein anderes Wiki sein. Es wird dann nochmal in das firmenweite Wiki exportiert, dass es dort auch verfügbar ist und so weiter. Das heißt, ja, eigentlich genau wie der Quellcode kann ich die Doku jetzt genauso behandeln.
Und gerade diese Kleinteiligkeit, die ich vorhin meinte, ich versuche meinen Quellcode zu modularisieren, kann ich auch meine Doku modularisieren und kann da sehr schön die Sachen wieder zusammenbauen, kann verschiedene Ausgabe sowohl inhaltlich Dokumente als auch von der technischen Seite, PDFs, HTML und so weiter erzeugen, auch parallel. Und das
Ganze bin ich dann auch in meine CI/CD-Pipeline ein. Das heißt, wenn die Software gebaut wird, wenn ich eine neue Version baue in der Software Version 7.3, dann wird die Doku einfach mitgebaut in der Version 7.3, liegt dort. Die Version 7.2 gibt es auch noch, die liegt in einem anderen Verzeichnis. Ich komme immer an alles ran. Also, ist so einfach eigentlich. Kann man gar nicht viel mehr sagen.
Ja, im Prinzip hat man ja auch, ich habe das in einer anderen Folge mal auch, haben wir das mal ein bisschen adressiert, das war auch ganz schön, um auch dann zu prüfen, ist denn die Dokumentation da oder hat sie sich geändert? Weil wenn sich was quasi vom Inhalt ändert am Sourcecode, dann wäre ja auch schön, wenn die Dokumentation irgendwie dazu ändert und nicht gleich bleibt. Solche Sachen, solche Prüfungen kann ich ja in so eine Pipeline ja dann auch einbauen, wo ich dann Vergleiche habe.
Was ich so Metriken habe und die dann auch messen. Es gibt natürlich jetzt verschiedene Sachen, die man da machen kann. Einerseits könnte ich aus dem Quellcode auch Sachen generieren, Diagramme oder auch Textschnipsel, die ich dann wieder in die Doku einbette. Das ist auf jeden Fall auch ein valider Weg, um so Rendanzen zu vermeiden. Und dann habe ich gar keine Arbeit. Und weil sich der Quellcode ändert, ändert sich dann quasi auch das
Dokumentations-Artefakt. Und ein anderer Schritt ist natürlich, dass ich, was ich vorhin meinte, dieses Continuous Documentation auch so einen richtigen Review-Prozess drumherum aufbauen
kann, weil es ja so ein Kreislauf ist. Und das heißt dann, dass wenn ein Entwickler ein neues Feature implementiert, was auch Auswirkungen auf die Architektur hat, und wir sind ja bei Architektur-Dokumentation, aber wie gesagt, gilt auch bei Benutzerhandbuch oder so, wäre ja auch nicht anders, oder Test-Dokumentation, wie auch immer, dass er dann quasi Definition of Done hat man ja, dass er da bestimmte Sachen abarbeiten muss
und da gehört die Dokumentation dazu. Und dann gibt es ja jemand, der es reviewt. Es gibt Code-Review, könnte das mit drin sein oder andere Arten von Reviews. Und wenn dann der Kollege, der Reviewt sieht, der hat zwar den Code angepasst und das funktioniert auch alles, die Tests sind da, aber die Dokumentation fehlt, dann fällt das ja auf und dann wird es nicht gemerged und dann muss man halt nochmal ran. Und dann ist das aber eben Teil von dem
ganzen Prozess. Und ich glaube, das Problem, ich habe ja vorhin schon gesagt, wir haben die anderen Tools, die uns dann schwerfallen, wenn wir das wechseln, Kontext wechseln, die kann man dann auch im Review nicht so einfach einbeziehen, weil man dann die Unterschiede nicht, man kriegt den Diff nicht direkt. So sieht man es ja im Pull-Request, den Diff
auch und das macht es dann eben leichter zu integrieren. Das ist eigentlich schon so ein bisschen dieses Continuous Documentation in ein paar Worten erklärt. Ja, sehr interessant. Du hast gerade ein spannendes Begriff noch gebracht und zwar das Generieren von Dokumentation. Da würde ich gerne noch deine Meinung dazu hören, was so die Sinnhaftigkeit betrifft und ob das, wenn ich das eine oder das andere generiere, ist es dann wirklich eine Doku oder wie siehst du das so?
Ja, also der Quellcode ist ja immer da. Das heißt, wenn man Informationen braucht, die da stehen, dann würde ich die jetzt nicht unbedingt noch mal redundant irgendwie, auch wenn es nur generiert ist, ablegen, weil es liest ja auch keiner. Man muss ja Dokumentation auch möglichst schlank halten, dass die Akzeptanz bei den Lesern auch da ist, wenn die dann immer ständig das lesen, was sie im Quellcode schon sehen, dann ist das natürlich auch
übertrieben. Und ich finde, man sollte solche Sachen generieren, die beispielsweise eben im Quellcode vielleicht nicht so eindeutig rauslesbar ist und gerade Softwarearchitektur steckt im Quellcode ja nicht so drin. Das ist das große Ganze, was das zusammenhält,
das sieht man dann erst mal nicht. Tatsächlich kann man, es gibt so Werkzeuge, Frameworks, die so Metainformationen im Quellcode, die man dran schreiben kann, um zum Beispiel Domainschiffendesign-Elemente, so was wie Bounded Context, Aggregates, Value Objects zu markieren und das dann zu nutzen und daraus dann wieder ein Diagramm zu erzeugen. Also aus dem Code mit den Metainformationen wird dann ein Diagramm erzeugt, wo man die Bounded Contexte sieht oder ein schönes Aggregate
mit seinen Value Objects und Entities beispielsweise. Das fände ich wieder wertvoll, insbesondere wenn es automatisiert passiert und jede Änderung, die im Quellcode passiert, auch sofort in der Doku wieder sichtbar ist. Und so kann ich mir gut vorstellen, dass man da gezielt, da wo es eben passt, was sich das dann macht und da wo man sagt, das ist jetzt irgendwie
unnütz und verschmutzt sozusagen in der Doku, dann würde ich es auch weglassen. Es gibt da tatsächlich oder ich kenne da jetzt nicht wirklich ein Werkzeug, was genau das schon tut allgemein. Ich habe gehört, manchen Branchen, wenn die da schon eine Anforderung haben, haben die sich manchmal selber was gebaut, was dann auf sie ausgerichtet ist. Es ist aber auch
nicht schwer, so was selber zu bauen. In der Softwareentwicklung kann man, wenn man die Anwendung testet, kann man auch einen Test schreiben beispielsweise, einen automatisierten Test, der auf den Quellcode zugreift und dort Informationen rausholt und daraus dann ein QML-ASCII-Doc-File wie auch immer zu erzeugen. Und das wird dann wieder in der Doku gerendert. Also kann man wunderbar alleine selber hinzufügen, den File, den man braucht.
Ja, super. Falk, vielen lieben Dank für diese Einsichten und diese Ideen dazu, wie man so Dokumentation auch leichtgewichtig gestalten kann. Ich glaube, da können sich einige Entwicklertests, agile Teams noch was abschauen, da in die Richtung auch mehr zu gehen und gute Dokumentation zu haben, die auch allen hilft und auch quasi leicht zu erstellen ist. Ich glaube, das ist
immer, dass diese Hürde da auch genommen wird. Das ist total wichtig. Ich danke dir schön, dass du hier warst und ich wünsche dir noch ganz viel Spaß jetzt bei den letzten Stunden der OOP. Hat Spaß gemacht. Vielen Dank, dass ich hier sein durfte. Ja, fand ich toll. Dann bis bald. Bis bald. Ciao. [Musik]