# Agile Documentation Strategy for Software Teams

**Podcast:** Software Architektur im Stream
**Published:** 2026-02-02

## Transcript

Hallo, ich bin Ibert Wolf.
Freitags mache ich oder Lisa Moritz ein Livestream zum Thema Softwarearchitektur, oft zusammen mit Gästen.
Dieser Podcast is das Audio des Streams.
Weitere Folgen, Sketchnotes und vieles mehr findet ihr unter software-architektur.tv.
Softwarechitektur im Stream.
Ja, hallo und herzlich willkommen zu einer neuen Folge von Software Architektur im Stream.
Heute mit Liam Berg.
Wir haben das Thema agile Dokumentation.
Liam, stell dich mal kurz vor.
Ja, mein Name ist Liam Berg, wie schon gesagt.
Ich komme ursprünglich aus der Softwareentwicklung.
Ich habe teilweise Legacy, also vor allem Legacy Code gepflegt und ich bin dann aber in die Dokumentation gewechselt, weil ich gesehen habe, dass da einfach ein großer Bedarf ist und habe mich dann auch letztes Jahr selbstständig gemacht und habe jetzt eine Firma, die Beratung für Dokumentation und Wissensmanagement anbietet.
Okay, Dokumentation, du legst gleich Wert auf agile Dokumentation.
Wo siehst du da den Unterschied?
Was ist da für dich so wichtig an diesem Aspekt?
Also ich kann jetzt natürlich primär von mir sprechen.
Ich muss sagen, mit Dokumentation habe ich oft so ein bisschen die Assoziation gehabt, dass es einfach Berge vom Papier, das sind einfach unglaublich viele Dokumente, die verstreut liegen und im Endeffekt sind sie oft veraltet und enthalten Informationen, die vielleicht auch gar nicht relevant sind.
Und das im agilen Kontext funktioniert, also ich meine, es funktioniert grundsätzlich nicht, wenn Doku so ist, aber im agilen Kontext ist es gerade, wenn man darauf ausgelegt ist, so halt immer wieder flexibel etwas zu verändern und sich auf gegebenheiten anzupassen.
Dann funktioniert es halt auch nicht umfassende Dokumentation im Vorfeld zu schreiben für alles.
Ich hatte da auch ein sehr interessantes Interview gelesen mit James Groening, das ist einer der Unterzeichner des Agilem Manifests, der eben auch darüber geredet hat, dass es vor dem agilen Ansatz üblich war, dass man sehr viel Dokumentation vorab geschrieben hat, wo man alles definiert hat, wie die Software werden soll und alles vorweg schon mal dokumentiert hat und dann halt danach das Programmieren begonnen hat.
Und das hat natürlich irgendwo Vorteile, weil man in der Theorie zumindest eine gewisse Sicherheit hat, man hat eine Planbarkeit, man hat feste Absprachen mit dem Kunden.
Ich glaube, ich muss jetzt nicht erläutern, warum das in der Praxis nicht immer funktioniert hat.
Aber dadurch, dass dann halt die agilen Ansätze kam, musste auch so ein bisschen dieser Herangehensweise an Dokumentation dann eben angepasst werden, weil man eben nicht mehr vorweg alles dokumentieren kann, wenn man erst im Verlauf des Projektes wirklich fest entscheidet, was umgesetzt wird und wie es umgesetzt wird, weil man vielleicht auch neue Learnings hat.
Und dadurch ist halt agile Doku, finde ich, nochmal so ein bisschen anders, weil man sich genau fragen muss, was ist jetzt überhaupt relevant.
Man kann nicht einfach umfassend alles dokumentieren, wenn man es im Zweifelsfall wieder ändern muss.
Sondern man muss im Grunde auch die Doku agil schreiben und immer eben hier und jetzt entscheiden, was ist für uns relevant, was müssen wir dokumentieren, was müssen wir festhalten, aber das auch möglichst schlank halten und nicht unnötigen Ballast mitschleppen.
Aber wenn ich jetzt mal ganz frech bin, ich kenne viele Entwickler, die sagen, agile Doku, wir sagen doch working software over documentation.
Wir schreiben doch überhaupt keine Dokumentation mehr.
Da kann ich jetzt ja mal ganz frech zurückantworten.
Das heißt, Working Software over comprehensive documentation.
Also erstmal für die Korrektur.
Ja, also im einen, zum einen natürlich wird gesagt, funktionierende Software ist wichtiger oder ist es als Wert höher anzusiedeln.
Es wurde aber nie gesagt, es ist ja auch der letzte Satz, also ich kriege ihn jetzt vielleicht nicht mehr ganz zusammen, aber während wir die Werte auf der linken, ist die linke Seite, ne, auf der linken Seite als wichtig oder als die linke Weiter auf der rechten Seite als wichtig einschätzen, sind die auf der linken Seite wichtiger.
So, das heißt, es wurde nie gesagt, dass Dokumentation nicht wichtig ist.
Funktionierende Software ist nur wichtiger und sollte die höhere Priorität sein.
Und ich gerade auch nach diesem Interview würde ich sagen, es geht halt auch so ein bisschen darum, dass man sagt, wir müssen nicht um jeden Preis alles dokumentieren, sondern vor allem das, was relevant ist.
Also nicht mehr umfassende Comprehensive Documentation von allem, was wir finden, sondern lass uns mal überlegen, was wirklich relevant ist.
Aber jetzt ist Dokumentation ja auch so, also viele Leute sagen, ein verhasstes Thema.
Ich merke aber doch manchmal, dass sich doch Entwickler dafür interessieren.
Wie ist da deine Sicht?
Dokumentiert man gerne oder sagt man lieber, hey, da steht Working Software over und die Software läuft immer noch nicht.
Also ich mache, ich investiere lieber in die Software.
Also ich muss sagen, ich glaube, ich bin auch da mal ein Einzelfall.
Ich dokumentiere tatsächlich gerne.
Ich würde aber behaupten, da bin ich relativ alleine.
Weil ich schon denke, es hat zum Beispiel was damit zu tun, wenn man aus der Entwicklung kommt, denke ich, man ist es natürlich gewohnt, dass wenn man Code schreibt, dann hat man am Ende was Ausführbares, was was funktioniert und hat ein Erfolgserlebnis.
Bei der Dokumentation dauert es im Zweifelsfall sehr lange, dass man da Ergebnisse sieht, dass vielleicht Kollege und Kolleginnen dann kommt und sagt, ey, das habe, da habe ich mal reingeguckt, das hat mir voll geholfen, vielleicht kriegt man auch nie Feedback und dann ist es halt unglaublich undankbar.
Das zweite ist, ich denke halt, viele haben gerne Dokumentation, möchten sie aber trotzdem nicht schreiben.
Also ich habe auch gerne eine aufgeräumte Wohnung, aber deswegen räume ich nicht gerne auf.
So ist es so ein bisschen mehr dieses am Ende hat man gerne Dokumentation, aber darum kümmern ist halt immer ätzend.
Und ja, das ist einfach dann auch so ein bisschen, glaube ich, teilweise, wie soll ich das sagen, dass man, dass die Herangehensweise fehlt, dass man einfach nur weiß, ja, Dokumentation ist wichtig, aber das ist halt nichts Greifbares.
Und dass da so ein bisschen der Ansatz fehlt, okay, wie gehe ich das Thema Dokumentation an?
Und dadurch entsteht dann eben auch Unsicherheit und vielleicht auch Gefühle von Überforderungen von, okay, ich weiß gar nicht, was ich dokumentieren soll, das ist so ein großer Berg.
Ich mache jetzt lieber das, wo ich weiß, wo ich anpacken muss, nämlich den Code.
Diese Herangehensweise, hast du da Tipps, wie man jetzt im Agilen am besten an die Dokumentation rangeht?
Weil, wie gesagt, du hast ja selbst gesagt, die Leute schreiben gern Code, weil sie dann gleich ein Erfolgserlebnis haben.
Ja, und der Code ist nie fertig, also kommt man auch nie zur Dokumentation.
Was wäre da so dein dein Ansatz?
Was würdest du empfehlen als Vorgehensweise?
Das ist jetzt natürlich so, also erstmal würde ich da jetzt schon so ein bisschen monieren, wenn du sagst, die Dokumentation, das ist halt auch etwas, worüber ich oft gestolpert bin, dass man sich nicht mal unbedingt einig ist, was bedeutet die Dokumentation.
Dokumentation kann halt sehr vielfältig sein.
Und dann wäre halt der erste Schritt zu sagen, und also da geht das dann schon zum Beispiel rein, dass ich sagen würde, überlegt euch, wer die Zielgruppe ist.
Weil es gibt ja, man kann, es gibt Anwenderdokumentation, die ist, glaube ich, relativ bekannt.
Da ist die Zielgruppe halt, sind die User, die das Programm später verwenden sollen.
Aber es gibt ja auch Entwickler und Entwicklerinnen, die mit der Dokumentation, also mit dem Programm nachher arbeiten sollen, die das weiterentwickeln sollen, die brauchen ja auch eine gewisse Druck.
Also hat man Architekturdokumentation zum Beispiel.
Es gibt vielleicht auch, je nachdem Software, wenn sie ausgeliefert wird und vom Kunden selber bei sich installiert werden muss, dann braucht man eine Installationsdokumentation, Admin-Dokumentation.
Also da wäre halt für mich die erste Ansatz, sich zu fragen, okay, was für eine Art von Dokumentation brauchen wir überhaupt konkret für uns?
Also, und dementsprechend damit dann auch die Frage zu beantworten, für wen ist die Dokumentation?
Und dadurch beantwortet man dann indirekt auch schon weitere Fragen, nämlich, welche Informationen sollten in der Dokumentation enthalten sein, was dann wiederum dazu beiträgt, dass die Doku eben nicht unnötig aufgebläht ist und auch sehr umfangreich ist und dadurch eben auch sehr viel aufwendig, wieder sehr aufwendig zu pflegen, sondern dass man sich wirklich fragt, für wen ist die Dokumentation, welchen Sinn soll die Dokumentation erfüllen und dadurch auch so ein bisschen ja die Dokumentation eben schlank und relevant hält, was finde ich so das A und O ist beim agilen Ansatz.
Gleichzeitig ist es aber auch einfach, wie denke ich alles bei agil, auch so eine Frage der Kultur, dass man erstmal auch eine gewisse Bereitschaft oder ein gewisses Verständnis dafür schafft, warum Dokumentation wichtig ist und dass da alle an einem Strang ziehen oder zumindest ein Großteil und dass wirklich Leute verstehen, warum sie die Dokumentation schreiben und dass es nicht ist, weil irgendjemand aus dem Management gesagt hat, wir brauchen Doku, sondern weil die Doku wirklich eine Unterstützung ist und dass man da als Team wirklich zusammen dran arbeitet.
Das ist jetzt ein spannender Aspekt.
Weil du hattest jetzt die Anwender-Doku genannt und ich überlege gerade so, ja, ich bin so jemand, wenn er sich ein neues Gerät kauft, dann guckt er mal, ist da eine Anleitung dabei und ich lese sie.
Viel steht da nicht mehr drin, ja, weil die Geräte selbsterklärend sein sollen.
Wenn ich an die Developer-Doku denke, dann denke ich an viele eingespielte Teams, die sagen, hey, wir kennen unsere Software in- und auswendig.
Wir brauchen das nicht nochmal niederzuschreiben.
Weil wir wissen es ja alle.
Das heißt, das sind jetzt so zwei Bereiche, wo ich Probleme hätte, den Leuten den Wert zu erklären.
Wo siehst du den Wert?
Also bei der Anwender-Doku muss ich dir zustimmen, wobei ich bin sogar meistens von der Fraktion, ich gucke mir einfach gar nicht mehr die Bedienungsanleitung an, muss ich ehrlich sagen.
Ich erwarte einfach, dass es verständlich genug ist, das Design des Produkts.
Aber also zum Beispiel bei der Entwicklerdokumentation, da wäre jetzt meine erste Frage, okay, gibt es da also nie Onboarding oder Offboard?
Also, Offboarding muss man jetzt, dafür braucht man vielleicht nicht unbedingt Dokumentation, aber wenn jemand das Unternehmen verlässt, dann ist ja die Implikation in der Regel, dass diese Stelle auch wieder aufgefüllt werden muss, also folgt dann darauf meistens ein Onboarding.
Das heißt, und neue MitarbeiterInnen haben halt einfach nicht das Glück zu sagen, ja, ich arbeite seit zehn Jahren damit, ich weiß, wie das funktioniert.
Das heißt, für solche Leute wäre es halt schon hilfreich, da eine Dokumentation zu haben.
Klar kann man auch sagen, ja, wir stellen dann einfach eine Person ab oder diese neue Person kann dann im Team einfach ständig Fragen stellen.
Das frisst natürlich dann auch wieder Ressourcen und Arbeitszeit.
Auf der anderen Seite gibt es ja nicht nur die Entwicklungsteams, es gibt ja zum Beispiel auch Projektleitung oder Produktmanagement, wo man vielleicht auch einfach irgendwann auf einer Ebene ist, wo man nicht mehr über alles den Überblick haben kann, weil man vielleicht auf einer sehr hohen Ebene Entscheidungen treffen muss.
Das heißt, auf dem Level ist sicherlich auch eine Dokumentation sinnvoll.
Ich würde generell sagen, ab einer gewissen Größenordnung oder auch wenn man allein schon, wenn man auch innerhalb der Unternehmens in Teams wechselt, dann hat man ja dasselbe Onboarding-Problem.
Oder wenn man halt, wenn die Software, an der man arbeitet, einfach einen gewissen Umfang erreicht hat, sodass man eigentlich realistisch gar nicht mehr alles wissen kann.
Letztendlich, wie ich schon gesagt habe, es muss irgendwie das Verständnis dafür da sein, wenn Leute wirklich drauf bestehen, sie brauchen keine Doku, ja, dann würde ich da jetzt auch nicht unbedingt anfangen.
Sondern würde dann halt irgendwie, woanders Leute sagen, ja, uns fehlt hier Doku, dann da ansetzen.
Also ich muss ja zugeben, ich beneide die Leute, die sagen, hey, wir kennen unsere Software in- und auswendig, weil wenn ich.
Habe ich auch noch nie gehört.
Wenn ich Code schreibe, ja, und vier Wochen später reingucke, denke ich mir, wer hat denn den Mist geschrieben?
Und dann gucke ich in ein Blame und merke, oh, das war ich.
Also von daher, man entfernt sich ja auch von dem eigenen Code und muss ja manchmal das Zeug selbst nachschlagen.
Von daher, wie hast du so die Erfahrung vielleicht auch mit Vorgaben, dass man Dokumentation für ein Audit braucht oder dass vielleicht irgendwie eine Branche Dokumentationen vorschreibt.
Also ich meine Erfahrung grundsätzlich ist, dass in solchen Branchen die Dokumentation deutlich besser funktioniert und da deutlich weniger rumdiskutiert wird, ob man die Doku braucht oder nicht, aber klar, das ist auch dann kein Diskussionspunkt.
Ich würde jetzt allerdings, das ist jetzt natürlich vielleicht nicht gerade sinnvoll oder also unterstützt nicht gerade meinen Punkt, aber ich muss sagen, ich habe nicht unbedingt den Eindruck, dass die Dokumentation, die dann von den Leuten verfasst wird, zum Beispiel für ein Audit oder generell wegen gesetzlicher Vorgaben, dass die Leute deswegen sagen, ja, aber die Doku hilft uns auch, weil es auch da wieder eine Frage von Zielgruppe ist, die schreiben dann halt die Dokumentation für die Auditoren oder einfach nur, damit man es hat.
Und da macht man sich dann eben nicht so sehr die Gedanken, okay, wer liest das nachher, weil welche Informationen braucht die Person, wie profitiert man davon?
Sondern es muss halt gemacht werden.
Aber mein Eindruck ist halt in dem Fall eher, ja, es wird gemacht.
Ich habe aber nicht unbedingt den Eindruck, dass es wirklich, dass da dann wirklich geschätzt wird, zu sagen, ja, wir haben das doch aufgeschrieben, lass uns das mal nachgucken, weil es halt nicht für die Zielgruppe der internen MitarbeiterInnen gemacht wird, sondern für eine externe Zielgruppe, die da halt irgendwie, weiß ich nicht, Sachen so abprüfen muss.
Und dann ist die Doku halt im Endeffekt trotzdem nicht dazu da, intern wirklich zu helfen und Wissen zu sichern.
Das erinnert mich so ein bisschen an so Source-Code-Dokumentation, wenn da eine Variable namens Counter deklariert wird und als Kommentar dann Fehler dran steht oder sowas.
Oder the counter, ist nicht wirklich hilfreich.
Hast du da Tipps und Tricks, wie man irgendwie das Zielgruppenorientierter aufbauen kann, dass man sinnvolle Dokumentation erstellt?
Das kommt jetzt vielleicht überraschend, aber erstmal die Zielgruppe fragen oder mit der Zielgruppe reden, sie, sofern es geht, einbinden.
Ich meine, das geht vielleicht nicht immer gerade, wenn die Ziel, wenn jetzt, was ich gerade sagte, die Software wird ausgeliefert und der Kunde vor Ort muss, die sich selber installieren, dann ist es schwierig, mit der Zielgruppe in Kontakt zu kommen.
Wenn wir jetzt aber davon reden, wir machen Dokumentation intern für unsere Software-Teams, dass man die Software-Teams wirklich aktiv mit einbezieht und sagt, okay, was würde euch helfen, diese Hürde zu überwinden, Doku zu schreiben, zum Beispiel braucht ihr, also hilft es euch, wenn ihr Vorlagen habt, die ihr einfach ausfüllen müsst, sodass ihr nicht selber diesen Mental Workload habt, von was ist wichtig, was ist irrelevant.
Ist es vielleicht auch eine Sache, so, also dann ist auch das Tooling ganz wichtig.
Zum einen, dass das Tool, das man benutzt, falls man halt wirklich Tools benutzt, das ist vielleicht so ein bisschen, ich möchte den Begriff etwas weiter fassen.
Also in dem Sinne wäre Gate for mich jetzt auch ein Tool und auch eine Entwicklungsumgebung.
Dass man sich auch überlegt, okay, dass wir das richtige Tool auswählen zu Documentationserstellung.
Zum einen, dass der Output in einer Form ist, wo er von der Zielgruppe auch konsumiert wird.
Weiß ich nicht, wenn man jetzt weiß, die Zielgruppe, das sind alles ältere, nicht technikaffine Menschen, dann ist es vielleicht ungünstig, wenn der Output immer nur als Webseite generiert wird, sondern dann sagt man, okay, lass uns das vielleicht als PDF machen, die man ausdrucken kann, weil unsere Zielgruppe lieber was aus Papier haben will.
Wenn man aber sagt, so das sind EntwicklerInnen, dann sollte der Output vielleicht in Form einer README oder sowas direkt in ein Git eingebunden werden können.
Und gleichzeitig dann eben auch fragen, okay, wer soll die Doku denn schreiben?
Also wer soll die Information bereitstellen und da eben auch gucken, dass das Tool so aufgebaut ist, dass es auch für die Leute, die nachher die Doku schreiben sollen, eine geringe Hürde darstellt zur Benutzung.
Also wenn man jetzt sagt, die EntwicklerInnen sollen Dokumentation schreiben, dann wäre es meines Erachtens zum Beispiel eine gute Idee.
Also meine Erfahrung ist, dass sowas wie Conference oder so meistens nicht so gut ankommt.
Wenn man aber sagt, so, hey, kannst du in der REAMDE das vielleicht ändern und das ist halt was, was sie dann direkt selber, während sie noch am Code arbeiten, in der Entwicklungsumgebung machen können, dann ist die Hürde da deutlich geringer.
Also, das heißt, das Tool muss in dem Sinne sowohl zur Zielgruppe gehören oder zur Zielgruppe passen, die nachher die Doku lesen soll, aber auch zur Zielgruppe, die die Doku schreiben soll.
Da fehlt dann der Medienbruch, wenn man es direkt ins Readme schreiben kann und nicht erst noch ein Browser aufmachen muss und gucken muss, wo im Wiki.
Also das heißt, du würdest jetzt das Tooling auch zielgruppenorientiert machen.
Das heißt, der Entwickler soll ins Readme oder eben Doxis Code-mäßig schreiben.
Keine Ahnung, die Anwender-Doku, damit man sie als PDF veröffentlichen kann, vielleicht in der Textverarbeitung und für das Audit-Team, damit sie es auch abheften können, drucken wir es aus.
So ungefähr.
Zum Beispiel, idealerweise hat man natürlich da möglichst wenig verschiedene Tools, gerade wenn ein und dieselbe Person die Doku schreiben soll.
Weil das löst auch, habe ich festgestellt, löst dann auch Frust aus, wenn man dann sagt, okay, hierfür musst du dieses Tool benutzen, hierfür musst du dieses Tool benutzen und hierfür dieses.
Also idealerweise hat man dann am besten ein Tool, was dann alle Ausgaben, die man eben braucht, hat.
Manchmal geht es halt nicht.
Aber ja, das wäre im Grunde so genau das, was ich halt meine, dass man, dass das Tooling da auf alle beteiligten Zielgruppen passt.
Wir haben die ersten Kommentare hier bei uns im Feed.
Daniel Pisanu, Doku aus der Audithölle namens A-Spice, da wird es C, wenn man das Agile macht.
Kennst du Ace-Spice?
Ich habe immer mal davon gehört.
Ich glaube, das ist irgendwas, um auch so eine Traceability herzustellen.
Kommt, glaube ich, tatsächlich aus irgendwelchen Anforderungen.
Aber ich habe es so selbst nie gesehen.
Dein Blick entnehme ich gerade auf, dass du dem auch noch nicht begegnet bist.
Aber so wie es Daniel beschreibt, sollte man dem auch ausweichen, habe ich so ein bisschen das Gefühl.
Und Alexander Much schreibt: über ja, wie viel Dokumentation braucht man?
Das kriegt man ja auch vielleicht über die Abdeckung beim Testen mit.
Das Maß, wie viel Dokumentation, gerade im Agilem ist ja jetzt echt ein Punkt.
Vor allem, man möchte ja auch nicht veralteten Dokumentation haben.
Und ständig irgendwie nur weil man irgendwie eine kleine Änderung gemacht hat, zum Beispiel im User Manual die Screenshots nachziehen müssen oder so.
Hast du dafür den Umfang, was zu dokumentieren ist?
Tipps, Erfahrungen?
Also erstmal ist es jetzt natürlich schwierig, pauschal eine Antwort zu geben, weil natürlich auch, also das wird ja allein schon vom Umfang des Softwareprojekts abhängen und des Teams und allen Menschen, die daran arbeiten.
Mein Tipp für eine Herangehensweise wäre da einfach, dass man dass man das im Grunde auch agile angeht und iterativ aufbaut.
Das heißt, man guckt erstmal, was ist bei uns der größte Painpoint, wo wir unbedingt wirklich sagen, wo die meisten an Board sind und sagen, wir brauchen Dokumentation.
Und sich da dann erstmal auf diesen Punkt fokussiert und sagt, okay, wir bauen das jetzt erstmal auf, so dass wir halt so ein kleines Increment, sag ich mal, haben an Dokumentation.
Und überlegen wir uns dafür eben auch, wie man, wie wir das in unsere vorhandenen Arbeitsprozesse mit einbinden, dass wir die Dokumentation auch regelmäßig pflegen.
Is this in, wie gibt es Möglichkeiten zur Automatisierung?
And when that funktioniert, dass man dann vielleicht auch wirklich in den Retrospektiven, wenn man jetzt nach Scrum macht, da auch regelmäßig, muss ja vielleicht nicht bei jeder sein, aber dass man regelmäßig auch mal guckt, funktioniert das für uns, haben wir noch andere Pain points, müssen wir vielleicht auch die Prozesse anpassen, funktioniert es nicht, diese Doku aktuell zu halten oder gibt es auch Frustration, weil Leute sagen, ich weiß gar nicht, warum ich das schreiben soll.
And that man vielleicht auch irgendwann sagt, okay, damals brauchten wir in diesem Bereich Doku.
Aus welchem Gründen auch immer hat sich jetzt was geändert.
We must vielleicht auch nicht mehr mit dokumentieren, aber dass man, wie gesagt, erstmal so ein kleines Inkrement, sag ich mal, schafft and then weiter halt durch reflektieren, guckt, okay, brauchen wir noch mehr Doku, sollen wir dann noch was dazu nehmen?
Müssen wir vielleicht auch die Prozesse wieder anpassen?
Passt vielleicht das Tooling auch nicht mehr, dass we for five Jahren mal gekauft haben, weil es wirklich gut war, but it has bei uns eben in der Firma so viele Sachen verändert, dass wir da jetzt einfach was anderes brauchen.
And that man sich langsam rantastet anders, is this, sag ich mal, from Pflegeaufwand her noch in Ordnung, oder entsteht da auch viel Frust by the MitarbeiterInnen, die sagen, ich weiß gar nicht, warum ich das schreibe.
Auf der anderen Seite is es eben auch, liefert es wirklich alle Informationen, wo Leute sagen, das sind Informationen, die erwarte ich von der Doku.
Oder hat man da vielleicht auch noch offene Stellen, wo man sagt, yeah, this won't we vielleicht auch noch in Zukunft dokumentieren.
And then this langsam so aufbaut und es wird halt, nee, würde ich mal sagen, wie das beim Agil so typisch is, is halt eigentlich, man ist nie fertig, sondern es ist immer, irgendwann kommt man an einen Punkt, wo man dann wahrscheinlich immer so ein bisschen austarieren muss.
Du hast jetzt öfters mal das Wort Prozess in den Mund genommen.
Ist das für dich so ein abstrakter Prozess, weil es sind halt Abläufe, oder würdest du diese Dokumentationsprozesse dokumentieren und festhalten, dass man sich streng daran hält?
Also ich persönlich würde sie natürlich dokumentieren.
Ich würde jetzt aber nicht pauschal sagen, dass das immer sinnvoll ist.
Man sollte sich, ich meine, das ist auch wieder so die Frage, ist das Unternehmen groß genug, dass man wirklich sagt, wir müssen hier die Geschäftsprozesse mal ordentlich dokumentiert haben, dann sollte man das auf jeden Fall damit aufnehmen.
Wenn man jetzt aber sagt, wir sind vier Leute, wir untereinander, wir besprechen einfach, wie es läuft.
Wir haben jetzt nicht so viele und so umfangreiche Prozesse, dass man es dokumentieren muss, dann werde ich jetzt nicht hingehen und sagen, aber das müsst ihr dokumentieren.
Man sollte halt es auf einem Level haben, wo es allen klar ist, wo es für alle transparent ist.
Und ab einer gewissen Größe kommt man dann nicht umhin, es auch irgendwo schriftlich festzuhalten oder in Form, weil so Prozesse sind ja, finde ich, eher in Ablaufdiagrammen oder sowas besser festgehalten als reinen Text.
Das heißt, ja, ab einer gewissen Größe wird man wahrscheinlich nicht drum rumkommen, das irgendwo schriftlich festzuhalten, aber ich würde auch da dann halt einen sehr schlanken Ansatz verfolgen, weil ja, wie ich gerade sagte, die Idee ist, es ist was, was man kontinuierlich, wo man kontinuierlich so ein bisschen dran dreht.
Und wenn man dann sagt, ja, allein jetzt die Dokumentation für den Prozess der Dokumentation anzupassen, wird jetzt schon wieder einen halben Tag in Anspruch nehmen, ja, dann, also das kann halt nicht das Ziel sein.
Also agil umsetzen.
Genau.
Du hast jetzt auch davon gesprochen, hier, das müsst ihr dokumentieren.
Wie siehst du da die Rollenverteilung?
Wer ist für die Dokumentation zuständig verantwortlich?
Siehst du da eine spezielle Rolle oder siehst du das verteilt aufs Team oder ist die Antwort kommt drauf an?
Also als Architekt würde ich immer sagen, kommt drauf an.
Genau.
Am Ende des Tages ist die Antwort immer, kommt drauf an.
Ich würde aber sagen, in den meisten Fällen würde ich halt schon sagen, es liegt beim Team.
Wenn das jetzt eine Firma ist, die konkret einen technischen Dokumentator oder technische Dokumentatorin angestellt hat, ja, dann ist ja schon die Implikation dahinter.
Oder wenn man vielleicht sogar eine ganze Abteilung dafür hat, wobei dann sollte Doku auch nicht so das Schmerzthema sein, klar, dann sollte die Verantwortung schon bei denen liegen.
Wenn man jetzt aber wirklich sagt, so die Teams dokumentieren für sich selber, würde ich sagen, es ist auf jeden Fall eine Teamaufgabe.
Ich denke, es hängt auch, es hängt vielleicht so ein bisschen vom Team ab, ob man so sagt, wie bei Scrum, so es gibt dann irgendwie eine Rolle von einem, der da so ein bisschen den Hut auf hat.
Das kann sinnvoll sein und ab einer gewissen Größenordnung ist es vielleicht auch ein sinnvoller Ansatz zu sagen, einer hat da so ein bisschen den Hut auf, dass wenn man sagt, also wenn man eben irgendwie in einer Retrospektive oder sowas feststellt, ja, das klappt so mit der Doku nicht.
Wir müssen, glaube ich, einfach mal ein neues, da muss ein neues Tool her.
Dann muss es natürlich jemanden geben, der sich darum kümmert.
Und wenn man von vornherein jemanden bestimmt hat, der im Zweifelsfall für Doku-AnsprechpartnerInnen ist, dann wird das nicht so schwer sein, dafür den Verantwortlichen und die Verantwortung zu benennen.
Wenn man jetzt keine Verantwortlichen hat, kann natürlich die Situation auftreten, dass die Leute zwar was ändern wollen, aber sich keiner zuständig genug fühlt, sag ich mal, um da dann die Verantwortung zu übernehmen.
Das muss aber nicht in jedem Team ein Problem sein.
Grundsätzlich finde ich, sollte aber selbst wenn man jemanden hat, der da quasi den Hut auf hat, sollte das Bewusstsein da sein, dass die Doku, genau wie auch die Software, das Software-Enkrement auch ja immer gelen, dass die Doku das dem ganzen Team gehört, vom ganzen Team gepflegt wird und auch vom ganzen Team genutzt wird.
Und dass man halt nicht sagt, ja, hier, wir haben einen, nein der schreibt da immer und wir kümmern uns da nicht drum.
Jetzt haben wir ja tatsächlich das Thema agile Dokumentation und agil, damit verbinde ich immer Sprints, somit die Abläufe.
Wir starten einen Sprint, wir wählen Storys aus dem Backlog und arbeiten an den Storys.
Wo würdest du da in diesem Prozess tatsächlich die Dokumentation sehen?
Ich höre immer mal wieder von Dokumentationssprints.
Macht das Sinn oder wie sollte ich das Ganze angehen?
Dokumentationssprints, also wahrscheinlich gibt es eine differenziertere Betrachtung.
Ich würde allerdings jetzt pauschal eher davon abraten.
Die Idee von einem Sprint ist ja auch, dass man am Ende halt was fertiges hat, was man präsentieren kann, was halt nicht nur Selbstzweck ist.
Und jetzt ist Dokumentation zwar kein Selbstzweck, aber es bringt ja das Produkt, an dem man arbeitet, nicht voran, wenn man Dokumentationssprint hat.
Und funktionierende Software über umfassende Dokumentation und das widerspricht ja eigentlich so ein bisschen diesem Ansatz.
Und die Dokumentation, ich finde, wenn man an dem Punkt ist, wo man sagt, es besteht eine Notwendigkeit für einen reinen Dokumentationssprint, dann zeigt das ja eigentlich nur, dann ist es ja nur Symptom eines ganz anderen Problems, nämlich dass die Dokumentation eben nicht schon im gelebten Alltag gepflegt wird, sondern dass es was immer noch was Nachgelagertes ist.
Und ich muss auch sagen, ich habe das einmal miterlebt.
Wir haben einmal in einem Team, wo ich war, ein Dokumentationssprint gemacht.
Fazit war, wir haben fast keine Story fertig bekommen in diesem Sprint.
Und haben dann letztendlich, ich weiß nicht, das waren irgendwie, also ich meine, am Ende des Tages sind Punkte natürlich relativ, aber es sind irgendwie, weiß ich nicht, glaube ich, über 70 Punkte gewesen, die wir dann in die nächsten Sprints mit reingezogen haben und dann über Wochen wieder abgearbeitet haben, wo ich mir denke, also das war halt ein absoluter Flop, dieser Dokumentationssprint.
Und das hat dann auch die anderen Teams davon überzeugt, es bei sich anders zu machen.
Hört sich danach an, dass ihr da viel technische Schuld aufgebaut habt.
Und du hast jetzt gesagt, dass die Dokumentation ja nicht zu Featern beiträgt, aber trägt sie nicht zum Werterhalt der Software bei?
Hoffentlich.
Jetzt ist aber, also ich habe halt so die Meinung, dass Dokumentation ohne die Software ist halt wertlos, weil Dokumentation nur im Kontext der Software funktioniert.
Die Software im Zweifelsfall kann ihren Job auch tun, ohne dass die Dokumentation existiert.
Und deswegen Dokumentation ist immer an die Software gekoppelt und im Grunde ist der Wert der Dokumentation von der Software abhängig.
Deswegen finde ich, es ist auch ein sehr guter Ansatz zu sagen, funktionierende Software über umfassende Dokumentation.
Und ja, im Endeffekt kann ich jetzt so wieder auf den Punkt zurückkommen, den ich vorher gesagt habe, wenn man an diesem Punkt ist, wo man sagt, lassen uns einen Dokumentationsspritt machen, wir haben so viel Doku noch zu schreiben, dann, ich meine, es kann vielleicht für manche Teams funktionieren.
Ich will jetzt nicht pauschal sagen, naja, das wird nie funktionieren.
Ich kann mir nicht vorstellen, dass es in der Regel funktioniert.
Und wie gesagt, eigentlich ist es auch ja nur ein Symptom für ein anderes Problem.
Und dann wäre vielleicht eher der Ansatz zu sagen, ich meine, ja, vielleicht muss man einmal wirklich sagen, wir arbeiten jetzt alles, was sich angesammelt hat, ab.
Letztendlich kann das aber nicht die Lösung sein.
Die Lösung muss dann sein, hinzugehen und zu schauen, warum hat sich so viel angesammelt und was müssen wir an unseren aktiven, in unserer Arbeitsweise wirklich aktiv ändern, dass sich nicht wieder so viel ansammelt, weil Dokumentation eben nicht nachgelagert irgendwann später passieren sollte.
Was ist jetzt dein konkreter Vorschlag?
Wie baue ich das in den in die agile Arbeitsweise ein, damit sich eben nichts ansammelt?
Also ein Ansatz kann zum Beispiel sein, wenn man genauso wie man halt sagt, okay, Software wird erst geschrieben, dann wird sie getestet, dann kommt eine Code-Review und dann erst wird halt die Neuentwicklung, sag ich mal, auf den Main Branch gemerkt.
Dass man da genauso wirklich konkret sagt, in diesen Schritten, ist dazwischen einfach auch noch ein Schritt, dass die Doku geschrieben wird, dass man wirklich sagt, das gehört fest mit rein.
Dass man dementsprechend dann auch sagt, jedes Ticket, also es ist einfach zu Definition of Done gehört, dass die Dokumentation geschrieben ist.
Jetzt ist natürlich auch immer so die Frage, wie man Tickets schneidet anders and worüber Tickets sind, weil manchmal gibt es halt auch einfach Tickets.
Also, das war zum Beispiel bei uns dann auch ein Diskussionspunkt, muss man das bei Bugtickets auch machen, weil in der Regel sollte bei einem, also die Idee, oder wo wir uns danach darauf geeinigt haben, war dann, okay, nein, bei einem Bugticket wird keine, muss keine Dokumentation angepasst werden, weil die Dokumentation, also außer man hat jetzt technisch eine große Änderung gemacht, aber bei den kleinen Bucket-Tickets zumindest, ist die Idee ja, die Dokumentation dokumentiert ja, wie das Programm eigentlich funktionieren sollte.
Und der Bug ist ja ein Fehler, den man nicht gefunden hat.
Und wenn man den behebt, dann funktioniert das Programm auch wieder so, wie es sollte.
Und dann ist die Dokumentation ja schon richtig, sie muss also nicht mehr angepasst werden.
Das heißt, es kommt dann vielleicht auch wieder drauf an, was das Inhalt der Tickets.
Und man kann vielleicht nicht pauschal sagen, für jedes Ticket muss Dokumentation geschrieben werden, weil sonst hat man wieder vielleicht die Situation, dass die Dokumentation einfach aufgebläht wird, weil Leute einfach nur denken, ich muss jetzt irgendwas hier reinschreiben, ich weiß gar nicht, was ich schreiben soll.
Also da muss man ein bisschen gucken.
Grundsätzlich ist auch Automatisierung immer eine große Hilfe, wenn man halt ja zum einen natürlich guckt, was automatisiert werden kann, allein schon im Bereich der Doku, dass man aber vielleicht auch da beim Git dann irgendwie in eine Überprüfung reinmacht, das gesagt wird, hey, also gerade wenn die Doku auch verheiratet ist, irgendwie mit dem Git, dass man sagt, hey, ich sehe, es wurde nichts, was hier zu diesem zu diesem Pull Request gehört, da wurde nichts in das Doku-Projekt gepusht.
Du kannst jetzt einfach nicht, du kannst den Pull-Request so noch nicht abschicken, oder der kann so noch nicht genehmigt werden, dass man da automatische Prüfungen auch reinmacht.
Ja, es ist halt, das wären jetzt so die Ansätze, die ich sage, die würde ich, glaube ich, in den meisten Fällen empfehlen.
Man kann da sicherlich auch noch andere Dinge verfolgen.
Jetzt hast du von Doku-Automatisieren gesprochen und wir haben jetzt hier im Stream schon häufiger das Thema Gen AI angesprochen.
Und gerade wenn ich an ich den Tool-Herstellern glauben schenken darf, dann kann ich ja jetzt mit Gen AI einfach mal eine komplette Dokumentation schreiben lassen.
Und ich bin total glücklich, weil ich nur noch Code schreibe und die Dokumentation wird mir von der KI abgenommen.
Wie siehst du das?
Macht das Sinn?
Ja.
Also, ich glaube, du hattest da auch vor kurzem einen Post drüber bei LinkedIn, auf dem ich tatsächlich auch commentiert habe.
Und im Grunde, ja, General kann Teile der Dokumentation wirklich übernehmen, gerade wenn es so um Code oder sowas darum geht, den Code einfach oder die so einen groben Überblick über den Code zu dokumentieren und sowas.
Letztendlich, solange wir aber immer noch in der Pipeline Menschen haben, die Entscheidungen treffen und die Abwägungen treffen und die von sich aus sagen, okay, das und das und das sind Faktoren, die wir bedenken müssen, das kann die KI ja nicht wissen.
Also egal, wie man es am Ende macht, aber irgendwie müssen diese Menschen, die Entscheidungen getroffen haben, auch auf technischer Ebene, müssen es irgendwie dokumentieren, selbst wenn es nur ist, dass man mit einer KI redet oder chattet und das der KI sagt, aber das ist im Zweifelsfall auch schon Dokumentation.
Ja, die KI kann das dann nachher schön umschreiben, dass es besser klingt.
Aber solange noch Menschen irgendwie im Entscheidungsprozess mit drinstecken, müssen Menschen auch noch dokumentieren.
Also das ist zwar immer noch unumgänglich.
Aber wenn ich mir so auf Social Media die Posts angucke, dann arbeiten ja schon ziemlich viele dran, die Menschen aus dem Softwareentwicklungsprozess rauszunehmen.
Und Dokumentation, das ist doch für die Kommunikation zwischen den Menschen.
Ich könnte jetzt mal ganz fies behaupten, dass, hey, in Zukunft, wenn die KI alles übernimmt, dann brauchen wir ja überhaupt keine Dokumentation mehr.
Ich würde die Aussage jetzt nicht per se widersprechen.
Ich muss aber sagen, da bin ich jetzt zu wenig im Thema drin, um wirklich abschätzen zu können.
Ich nehme an, es wird Kontextgrößen geben, die groß genug sind, dass man wirklich sagen kann, ja, die KI, die liest sich das gesamte Programm durch und dann hat die alles, sag ich mal, im temporären Speicher, also in diesem Kontext.
Und ja, dann wird sie keine Dokumentation mehr brauchen.
Jetzt kann man natürlich darüber reden, ist das vielleicht nicht trotzdem Ressourcen schon da, eine Doku zu haben, die die KI liest und an der sie dann sich lang hangelt, um dann Erweiterungen am Code zu machen.
Da kann ich jetzt aber keine realistische Einschätzung abgeben, ob das wirklich am Ende Ressourcen schon da ist und dadurch eben günstiger, wenn man der KI eine Doku zu lesen gibt.
Ja, ich denke halt vor allem auch, dass die KI leicht dokumentieren kann, was der Code macht, aber nicht warum.
Das ist genau das, was du ja auch gesagt hast, dass wir immer noch den Menschen drin haben, selbst wenn man denen aus dem Entwicklungsprozess rausnehmen, haben wir vorne ein Anforderungsprozess, wo wir den Menschen haben, der vorgibt, warum ist das so und das kann die KI nicht aus dem Source Code rauslesen.
Ja, aber wenn die KI dann hauptsächlich, oder wenn die KI nachher eigenständig komplett programmiert, dann, also weil für mich jetzt die Implikation zumindest die KI dann auch selbstständig.
Genau, und ich muss zugeben, ist so mein Traum.
Ich bin mal gespannt, wie weit wir da kommen.
Ja, genau.
Jetzt, du hast von den README gesprochen, von der Softwaredokumentation.
Dokumentation ist ja nicht nur Text.
Was für verschiedene Komponenten siehst du bei der agilen Dokumentation?
Was ist wichtig?
Also, ich meine, es gibt ja auch die Teams, die sagen, wir machen das alles agil, wir treffen uns am Whiteboard, wir schmieren was auf das Whiteboard, danach haben wir uns ausgetauscht, wir wissen alles und löschen, wischen das Whiteboard wieder ab.
Das ist so ein Extrem.
Am Whiteboard kann ich schön Diagramme zeichnen und sowas.
Was siehst du da als gute Kommunikationsmittel in der Dokumentation?
Ich meine, wenn es für das Team funktioniert, werde ich jetzt nicht hingehen und sagen, nein, ihr könnt das so nicht machen.
Ich habe meine Zweifel, ob das langfristig gut funktioniert.
Ich meine, im Endeffekt erstmal, also wo du das jetzt gerade sagst, so mit was gibt es für Arten von Dokumentation.
Ich denke mir, im Endeffekt, Tickets zu schreiben, ist ja auch schon Dokumentation.
Das ist ja im Grunde nichts anderes als eine Anforderungsdokumentation.
Und je nachdem, wie tiefgreifend die Tickets sind, wenn man da dann auch am Ende wirklich, also das habe ich auch schon erlebt, dass dann, wenn in Meetings die technische Umsetzung diskutiert wurde, dann hat man auch wirklich das technische Konzept da schon mit reingeschrieben.
Das heißt, da sind Tickets ja auch irgendwie eine Form der Dokumentation.
Es ist halt wieder so eine Frage von es kommt so einfach, das kann man jetzt pauschal nicht beantworten.
Also ich so innerlich kriege ich so ein bisschen nervöses Augenzucken, wenn du sagst, ja, wir schreiben das auf dem Whiteboard und danach wischen wir es wieder ab und ich denke mir so, ihr könntet wenigstens ein Foto davor machen.
Ich denke schon, dass es ja also man muss halt die richtige Form für sich finden, das richtige Vorgehen ist.
Ich würde halt sagen, es gibt bei Agil nicht die eine richtige Art und Weise zu dokumentieren.
Und es kommt dann im Zweifelsfall halt echt aufs Tooling an.
Aber wie gesagt, Tickets sind auch schon Dokumentationen.
Ich hoffe doch, dass die meisten Teams zumindest in irgendeiner Form mit Tickets arbeiten.
Selbst wenn man sagt, das sind bei uns noch physische Karteikarten, wo wir nur ein Satz drauf schreiben.
Ja, aber selbst das dokumentiert ja zumindest eine gewisse Notwendigkeit, etwas umzusetzen.
Du hast dich ja auch in der Vergangenheit mit Diagrammen beschäftigt und dem C4-Ansatz.
Inwiefern hilft der C4-Ansatz, die Dokumentation zu strukturieren.
Ja, C4 ist natürlich, also einfach um jetzt nochmal so kurz die Leute abzuholen, die das vielleicht noch nicht gehört haben.
C4 ist, wie du schon sagst, es hat mit Diagrammen viel zu tun.
Es ist ein Ansatz für Softwarearchitektur-Dokumentation.
Und C4 hat halt zum einen die Grundidee zu sagen, wir haben feste Abstraktionsebenen.
Also es gibt da im Grunde vier, deswegen heißt es C4, weil es vier verschiedene Abstraktionsebenen gibt, wobei das eigentlich auch so ein bisschen aufgeweicht ist, weil die erste ist System Context, wo man halt so einen Überblick bekommt über das Software-System, um das es geht.
Dann hat man Container-Ebene, wo man Überblick über einen, also Container ist nicht Docker, ganz wichtig, sondern das ist einfach nur die Vokabel, die gewählt wurde.
Das heißt, ein Software-System besteht aus mehreren Containern.
Und Container-Ebene ist halt, wo man dann Überblick über Container bekommt.
Über einzelne.
Dann gibt es die Komponenten-Ebene oder Component.
Das ist dann die nächste tiefere Ebene.
Also ein Container besteht aus mehreren Components oder kann aus mehreren Components bestehen.
Und danach käme dann innerhalb, also nach der Komponente käme dann halt der Code.
Und das ist die vierte Ebene.
Da wird dabei in der Regel gesagt, wenn es nicht automatisiert ist oder aus irgendwelchen anderen Gründen wirklich dringend notwendig ist, am besten einfach weglassen, weil der Code sich so schnell ändert, dass man mit dem Dokumentieren nicht hinterherkommt.
Deswegen ist es eigentlich so mit den vier Ebenen so ein bisschen relativ.
So, und also das ist der eine Ansatz, der andere Ansatz ist, dass eben auch gesagt wird, wir einigen uns auf festes Vokabular.
Ich habe es jetzt gerade schon gesagt, Container, Component, System, Software-System.
Das sind so feste Vokabeln, die sind klar definiert, dass die Leute auch wirklich von derselben Sache reden, weil wenn ich jetzt sage, hier, also wenn ich jetzt ohne eine klare Definition einfach sagen würde, ja, hier die Komponente, dann könnte ich von der ganzen App reden, dann könnte ich auch nur von einer UI reden, dass man halt einmal feste Definitionen hat für verschiedene Vokabeln.
Also wie gesagt, das Wichtige sind Component, Container, Software-System, dann sind auch, da gibt es natürlich noch Beziehungen zwischen diesen Sachen.
Es gibt dann noch Environments, ich habe es jetzt ehrlich gesagt nicht mehr alles super präsent.
Das sind halt so die Grundideen von C4, dass man eben sagt, wir reden alle über dasselbe, also wir können uns verständigen, weil wir ein festes Vokabular haben und wir haben verschiedene Abstraktionsebenen, sodass man eben auch, und dann kommt auch wieder dieser Punkt Zielgruppenorientierung mit rein, weil nicht jede Abstraktionsebene für jede Person relevant ist.
Also die Projektleitung, die muss nicht wissen, was auf Code-Ebene passiert.
Oder so wenn man generell vom C-Level-Management redet, das ist sicherlich gut, wenn die auch wissen, wie die Software, die ihr Unternehmen herstellt, aussieht und wie sie aufgebaut ist.
Was ist da, weiß ich nicht, wenn man jetzt Microservices hat, was es da für einzelne Microservice oder so gibt, dass man einfach mal grob weiß, was haben wir.
Die müssen aber nicht im technischen Detail wissen, was da los ist.
Letztendlich Entwicklung oder auch als Software-Architekt oder Software-Architektin sollte man da schon einen besseren Überblick haben und technische Details besser einsehen können.
Wenn man das aber alles auf einen Diagramm packen will, dann wird es halt extrem unübersichtlich.
Und deswegen ist halt die Idee eben gewesen, wir machen ein ja einmal so ein bisschen so eine Draufsicht, die ist halt eher für nicht-technische Akteure.
Und dann gehen wir halt ein bisschen weiter immer in die Tiefe, sodass man halt, wenn man auf einer, also wirklich einen technischen Hintergrund hat und technische Informationen braucht, dann gehen wir da, dann haben wir halt andere Ebenen, die technisch deutlich detaillierter sind, wo man das auch ablesen kann.
Das heißt, diese Abstraktionsebenen siehst du auch wieder eigentlich Zielgruppenorientiert, dass ich da verschiedene Ebenen habe, je nachdem, wie tief ich runtergehe.
Genau, Zielgruppenorientiert.
Ja, es läuft im Endeffekt immer auf Zielgruppenorientierung raus.
Es hat natürlich auch irgendwie, es kann natürlich auch sein, dass auch als EntwicklerIn ich einfach nur mal einen groben Überblick haben möchte, dass ich auch mal links und rechts schauen möchte, was so außerhalb von meinem Microservice zum Beispiel, was die anderen Teams entwickeln, dann kann ich natürlich auch irgendwie die grobe drüber sich nehmen.
Dann ist es auch für mich als EntwicklerInnen interessant.
Im Endeffekt ist es läuft es aber darauf hinaus, ja.
Es gibt auch noch, es gibt dann bei C4 eben auch noch so Dynamic Diagrams, das sind im Grunde so Ablaufprogramme.
Es gibt auch noch, ich weiß jetzt gerade nicht, wie sie heißen, die sind aber, die zeigen dann wirklich die Infrastruktur, auf der die Architektur läuft.
Ich glaube, die heißen sogar Infrastrukturdiagramme.
Das ist dann zum Beispiel eben auch für so die DevOps-Gruppe interessant, für die Leute, die wirklich die Infrastruktur bereitstellen.
Also ja, es läuft immer wieder darauf hinaus, dass es eben für die richtige Zielgruppe, also dass die, dass es verschiedene Diagramme für verschiedene Zielgruppen gibt und dass da eben auch dann nur die relevanten Informationen drin sind, aber eben auch alle relevanten Informationen, damit es überhaupt auch irgendwie sinnig ist und das Diagramm auch einen Mehrwert liefert.
Im Chat hat Eberhard gerade darauf hingewiesen, dass wir tatsächlich bei Softwarearchitektur im Stream auch die Folge 36 haben, die nochmal detailliert auf C4 eingeht.
Ich glaube, die ist sogar mit Simon Brown, wenn ich mich recht erinnere.
Also für die Leute, die da eben nochmal tiefer reingehen wollen.
Ist das jetzt aus deiner Sicht etwas, was den agilen Dokumentationsprozess unterstützt oder was jetzt eher nicht so ins Agile reinpasst?
Ich würde sagen, dass, also ich denke nicht, dass es mit dem agilen Ansatz im Kopf direkt entwickelt wurde.
Also ist es jetzt nicht gezielt für den agilen Ansatz entwickelt.
Es funktioniert grundsätzlich.
Aber ich finde es, ich würde sagen, es harmoniert sehr gut mit dem agilen Ansatz, weil eben wirklich die Idee ist, wir teilen es so auf, dass die Information, dass immer nur die relevanten Informationen da sind.
Das heißt, da auch wieder das Thema, die Doku sollte schlank und relevant sein.
Des Weiteren ist auch eine Idee, die sehr stark mit C4 verknüpft ist.
Diagrams ist Code 2.0 nennt Simon Brown das ja, glaube ich.
Also Diagramms is Code, das denke ich klar, dass man die Diagramme macht man nicht mit einem grafischen Programm, sondern die werden eben als Code geschrieben, zum Beispiel Plant, UML und sowas.
Und Diagrams ist Code 2.0 ist eben so die Weiterentwicklung davon, dass man eben nicht mehr die reinen Diagramme beschreibt, sondern dass man in einer DSL in einer Domain-Specific Language eben die Architektur beschreibt.
Und dann kann man sich beliebig viele Diagramme daraus definieren und daraus ableiten.
Und man hat eine Single Source of Truths quasi, an der man nur noch Veränderungen vornehmen muss und alle Diagramme, die da halt raus generiert werden, die aktualisieren sich automatisch.
Und dadurch hat man dann auch wieder sehr wenig Pflegeaufwand und dadurch, dass es eben auch in Form von Code ist, ist es auch wieder, dann sind wir wieder beim Tooling.
Dann können auch die Leute, weil tendenziell werden ja, wird die Software-Architektur die Informationen darüber haben, die EntwicklerInnen und Software-ArchitektInnen.
Das heißt, die werden auch diejenigen sein, die dann wahrscheinlich die Doku anpassen müssen, wenn es Änderungen gibt.
Und für die ist es tendenziell, glaube ich, eine deutlich geringere Hürde, wenn sie es direkt in Form von Code machen können und einfach das als Code schreiben können.
Das heißt, es ist auch deutlich einfacher zu integrieren, da ist eine geringe Hürde und es verträgt sich dann sehr gut mit dem Ansatz zu sagen, Doku gehört einfach mit zum Arbeitsablauf, es sollte schlank sein, es sollte nicht groß, nicht viel Aufwand sein und man kann es einfach spontan schnell und einfach ändern.
Und ist damit, ja, wie gesagt, lässt sich da sehr gut mit verbinden.
Das ist dann natürlich auch so eine Form der Automatisierung, das, was du vorhin angesprochen hast, die wirklich Sinn macht.
Dass ich nicht gucken muss, ich habe hier eine Änderung an der Architektur vorgenommen, welche Diagramme muss ich wo aktualisieren, wo liegen die jetzt alles in welcher PowerPoint in welchem Wiki, sondern ich gehe halt her, ändere in diese DSL in dem Modell und lass mir die Sichten drauf generieren, was dann ja tatsächlich den agilen Prozess sehr schön unterstützt ist.
Doctorsis Code 2.0.
Hast du das Gefühl, dass das schon gut einsetzbar ist?
Oder bringt die DSL nochmal eine neue Komplexität rein?
Ich meine, natürlich, man muss am Anfang erstmal die DSL lernen, die ist aber tatsächlich sehr einfach, sehr simpel.
Und ich würde sagen, sie verzeiht auch sehr viel.
Also, es ist jetzt nicht so, ich würde sagen, ja, wie gesagt, sie verzeiht sehr viel.
Also man kann im Zweifelsfall auch Attribute weglassen.
Ich meine, Simon Brown sagt zwar selber, man soll immer einen Namen, eine Beschreibung und ab einem gewissen Level auch immer eine Technologie hinzufügen.
Im Zweifelsfall, wenn man das leer lässt, schimpft es aber auch nicht.
Und es ist halt, also es ist eine sehr simple Sprache eigentlich.
Man muss am Anfang, ich glaube, das Schwierigere ist eher, erstmal zu verstehen, den ganzen Ansatz von C4 zu verstehen und wirklich sich einmal wirklich damit auseinanderzusetzen, was sind Components, was sind Container, was ist ein Software-System.
Wenn man einfach mal den Grundgedanken davon verstanden hat, dann ist die DSL, gerade wenn man schon irgendwie Coding-Erfahrung hat und es richtet sich ja im Grunde an Programmierender, ist es sehr schnell zu lernen.
Also das war wirklich so, ich hatte das hier in einem Unternehmen halt auch mal komplett ausgerollt und ich habe dann halt den Leuten primär eigentlich den Ansatz erklärt von C4, was der Grundgedanke ist, und hab denen dann halt ein, zwei Code-Beispiele gezeigt und dann haben die, and then natürlich haben die sich am Anfang so ein bisschen da lang gehangelt, okay, wie initialisiere ich das jetzt, aber die waren dann sehr schnell in der Lage, wirklich einfach selbstständig da Software-Systeme mit Containern und Components und so wirklich komplett selber zu erstellen, weil es ja sehr intuitiv eigentlich ist.
Wenn man schon mal mit Code gearbeitet hat, ist da wirklich die Lernkurve nicht so nicht so steil.
Okay, das hat sich ja gut an.
Aber man muss das Tooling aufsetzen.
But wenn man in der Softwareentwicklung ist, dann hat man ja Spaß dran, das Tooling aufzusetzen.
Dann geht das ja.
Ich hoffe es.
Ja, this is tatsächlich so the ich, but I have on sowas tatsächlich kein Space, which halt sagen würde, das ist vielleicht eine Hürde, da wirklich ein Tooling to finden.
Man kann den Structurizer nehmen.
Irgendwas wurde offline genommen beim Structurizer.
It's irgendwie eine Cloud Lösing, glaube ich, or so eine Art Cloud Lösing, selber from Structure, also Structurizer is the Tooling von Simon Brown for C4.
Man can, also I feel me not sicher, we said offline.
It's about open source Projekte, die, when man halt nicht irgendwie diese Cloud-Lösung möchte oder diese Enterprise Lösung, dass man das bei sich zum Beispiel C4 da eingeführt habe.
Die haben dann auch eine Open Source Lösung genommen, so dass man erst mit einem Structurizer alles schreibt, aber dann halt nicht das in irgendeine Cloud laid or so, and that's about the structurizer darstellen lässt, sondern dass es dann einfach in the Git Pipeline wird dann anderes Tooling eingebunden.
I wish it's gerade gar nicht mehr, wie it's heißt.
Und dann wird das einfach eine Webpage erstelled.
Also da ist dann wieder hängt dann Plant-U-Mail mit drin.
Dann wird das alles in Plant-U-Mail umgewandelt und dann hat man einfach eine Webpage, die man selber hosten kann.
Und ist dann nicht halt irgendwie auf ein externes Tool angewiesen.
Und wenn man halt darauf aus irgendwelchen Gründen keinen Zugriff hat, dann sind auch die Diagramme weg, sondern man hat in Zweifelsfall eine Webpage, die man bei sich selber hostet, und selbst wenn das Tooling wegfällt, hat man immer noch die Webpage, die erstellt wurde.
Okay.
Das hört sich ja eigentlich ganz praktikabel an.
Jetzt, wenn ich mal so ein bisschen schon mal zusammenfassen kann.
Du hast jetzt gesagt, dass Dokumentation im Agilem auf jeden Fall nicht wegfällt, sondern nur Working Software wichtiger ist, dass wir unterschiedliche Dokumentationsarten entsprechend der Zielgruppe haben, dass wir die Dokumentation in den agilen Prozess reinnehmen sollten, in die Definition of Done, that auf jeden Fall in jedem Story, dass eben genauso wie es testen zum Fertigstellen der Story gehört.
Dass Tooling wichtig ist, dass unterschiedliche Elemente wichtig sind, dass es eben nicht nur einfach plain text is, sondern dass eben auch Diagramme wichtig sind und auch, dass die Automatisierung wichtig ist, dass man sich eben, dass man die Dokumentation so schlank wie möglich hält und dass man auch versucht, der Maintenance aus dem Weg zu gehen und versucht, nicht unbedingt technische Schuld aufzubauen, damit man nicht Dokumentationssprints machen muss.
Das fasst so eigentlich ganz gut zusammen, wie wir agil Dokumentation machen können, oder?
Ja, das Einzige, also ich meine, ich würde sagen, dass das eine sehr umfassende, sehr gute Zusammenfassung.
Das Einzige, wo ich jetzt vielleicht noch sagen würde, das könnte man noch ergänzen, dass es halt wirklich eine Kultur dafür da sein muss, ein Bewusstsein dafür da sein muss, warum man dokumentiert.
Weil ohne das funktioniert halt alles andere nicht.
Den Leuten muss bewusst sein, warum dokumentieren wir und nicht nur ja, weil irgendjemand das entschieden hat und Dokumentation hat eigentlich kein Wert für uns, sondern dass man wirklich auch eine Kultur dafür schafft und ein Bewusstsein dafür schafft, die Dokumentation ist für uns und sie soll uns helfen.
Und wenn sie das nicht tut, dann müssen wir daran was ändern.
Das ist eigentlich der wichtigsten Punkt, den ich in der Zusammenfassung vergessen habe.
Die kulturelle Grundlage.
Wenn die Leute nicht bereit sind und es nicht einsehen, dann ist es schwierig.
Und das ist dann halt in so einem eingespielten Team, was sagt, hey, wir kennen doch unsere Software, echt ein Problem.
Hättest du da irgendwie Vorschläge, wie man den Leuten das besser klar machen kann, dass man mal zum Beispiel Teams durchmischt und ihnen damit sagt, guck mal, ihr habt gar keine onboarding-Dokumentation, das ist jetzt ein Problem.
Ich meine, Teams durchmischen klingt nach einer super Idee, um den Leuten mal wirklich aufzuzeigen, ja, Dokumentation ist sinnvoll.
Es ist halt die Frage, ob man da vom Management das okay kriegt.
Ja, ansonsten, ich habe halt hier eher so, also ist halt die Frage, wenn man jetzt wirklich sagt, ich will meine KollegInnen überzeugen, da würde ich jetzt halt, ich meine, klar, wenn die Leute wirklich sagen, nein, ich brauche keine Dokumentation, ich weiß alles, dann sage ich mal, dann braucht man da auch nicht gegenargumentieren.
Letztendlich ist aber ich einfach sagen, so, okay.
Ist es dir nicht auch schon mal passiert, dass du nach irgendeinem, dass du irgendein Fehler gesucht hast und dann hast du nach fünf Stunden Debugging gemerkt, so das ist eigentlich gar kein Fehler.
Wir haben nur vergessen zu dokumentieren, dass das weiß ich nicht, dass das eigentlich geplante Verhalten war.
Oder ja, ich hätte den Fehler viel schneller gefunden, wenn ich es einfach mal dokumentiert hätte.
So, dieser Spruch, so stundenlanges Debugging kann einem fünf Minuten lassen, der Dokumentation ersparen.
Dass man da vielleicht auch einfach mal versucht, einen Bewusstsein zu schaffen, so, ey, wann hast du das letzte Mal im Ticket gesessen und hast dir nach drei Stunden debugging gedacht, boah, wenn ich das vorher gewusst hätte, dann hätte ich hier mir sehr viel Zeit sparen können.
Or I wish in which in some real problem is when that team completely said, ich weiß nicht, we listen this.
My beobachting in solchen Fällen ein reality is that many, two colleagues Problem ist, wenn das Team wirklich komplett sagt, also often gefragt werden, pass man auf, who wisst doch what this is.
Can you eran while I have here some ticket?
And that they then arbeits not with tier bringing, but with other Dinge zu erklären, weil sie nicht dokumentiert sind.
And that man da auch sagt: So, hey, willst du nicht manchmal einfach gerne a long ungestört programmieren, ohne that someone fragt, ohne that erklären muss.
So, then you couldn't the leute, when we have Doku had the Doku verweisen.
And they wouldn't iron hoffently aufhören, die ständig zu fragen.
Da fällt mir noch so eine eigenen Story.
Where the time these Blockbeiträge.
And genau so wie du es jetzt gesagt hast, hat er mir geantwortet, that spart ihm Zeit.
Weil immer when a frame, then beantwortet er nicht die Frage, sondern dann schreibt er darüber einen neuen Blogartikel, verweise then auf diesen neuen Blogartikel und weiß, dass er diese Frage hoffentlich nicht mehr reinbekommt, beziehungsweise wenn sie reinkommen, er auf diesen Blogartikel verweisen kann it's a lot of it.
Das finde ich eigentlich einen sehr guten Ansatz, um loszulegen, oder?
Dass man immer, even when many there is a frame, da ist irgendwo eine Frage, dass man mal guckt, haben wir eigentlich Dokumentation dazu?
Wenn nicht, dann lass sie uns schreiben, oder?
Damit wird man doch ganz gut agil anfangen können, um eben langsam die Dokumentationsbasis zu verbessern.
Ja, also ich will dem nicht pauschal widersprechen.
Ich sehe da nur das Problem, wenn man es auf Dauer so macht, dann wirkt das sehr viel Potenzial für Wildwuchs.
Weil dann bekommt dann eine Frage und denkt sich, ja, das sollte ich mal irgendwo hinschreiben und im schlimmsten Fall hat man dann irgendwie einen Confluence oder so und sagt dann, ja, ich erstelle hier irgendwo eine Unterseite und die findet danach auch keiner wieder.
Und dann hat man das Problem eigentlich nicht gelöst.
Also man muss sich, es wird irgendwann ab einer gewissen Größenordnung einfach der Punkt kommen, wo sich mal ein paar Leute zusammensetzen müssen und sagen müssen, lass uns mal irgendwie strukturiert das Ganze angehen, dann eine Ordnung reinbringen.
Und danach kann man dann natürlich wieder, ja, da füge ich hier noch was hinzu, da füge ich da noch was hinzu, aber man muss da sollte da eine Grundstruktur erstmal haben.
Das ist ein guter Punkt.
Der kommt ja auch gerade im Chat rein als Kommentar von DRE.
Wichtig ist auch die Auffindbarkeit der Dokumentation, klare, einheitliche Strukturen.
Wenn man die nicht hat, ist Write-Only-Dokumentation.
Sie wird geschrieben, aber nicht gelesen.
Ich kenne das auch so, dass ja, man am Ende des Projekts dann erfährt, ja, du, das, was du da gesucht hättest, das wäre da im SharePoint, guck mal, in Folder Level 15, da wäre es gewesen.
Ja, ich weiß, heißt Archiv der erste Folder, aber nee, da ist unsere aktuelle Doku.
Hast du da Tipps?
Wahrscheinlich, wenn man am Anfang sich Gedanken macht, was für Doku man braucht, dass man auch die Struktur aufbaut, oder?
Genau, also das sage ich mal, das ist vielleicht eine bittere Pille zu schlucken, weil das, ja, ich meine, ich würde nicht sagen, es widerspricht dem agilen Ansatz, denn auch bevor man beim agilen Ansatz das erste Inkrement fertig hat, muss man auch initial mehr Arbeit reinstecken, als man in allen folgenden Iterationen reinsteckt, würde ich sagen.
Das heißt, ja, es wird im Endeffekt ab einer gewissen Größenordnung, also wie gesagt, für zwei oder drei Leute, für so Teams, die ganz klein sind, ist es vielleicht nicht notwendig.
Aber ab einer hinreichend großen Personengruppe wird es einfach unumgänglich sein, sich wirklich mal hinzusetzen und zu sagen, wir brauchen eine Struktur, wir müssen uns vielleicht auch Vorlagen überlegen, also was soll wirklich konkret in die Doku rein und sich dann auch eben mal hinzusetzen und zu evaluieren, was ist das richtige Tool.
Also im Grunde ist es so, würde ich sagen, so ein bisschen wie so ein Onboarding-Projekt für die Dokumentation.
Also man muss, ja, einmal muss man da wirklich in den sauren Apfel beißen und sagen, wir stecken jetzt Arbeit da rein.
Ob man das jetzt als Dokumentationssprint bezeichnet, weiß ich nicht, weil der Sinn dahinter ja dann eigentlich nicht ist, alte Dokumentation zu erneuern, sondern wirklich mal zu sagen, wir führen jetzt hier eine neue, ja, ich werde sagen, Ära, aber wir führen jetzt hier was Neues einfach ein und dafür muss man, das ist ja egal, was man macht, wenn ein Unternehmen irgendwie sagt, wir rollen jetzt hier was aus, das macht man auch nicht so nebenbei, sondern da setzen sich ein paar Leute zusammen, man holt sich Feedback, man holt sich Input, was wird gebraucht und dann muss man einmal wirklich überlegen, was ist hier eine Lösung, die vielleicht, also im Idealfall macht man es auch unternehmensweit und zieht da alle Teams gleich, dass man auch wirklich, wenn Leute innerhalb von Teams wechseln, dass sie nicht nur die Doku haben, die ihnen beim Onboarding hilft, sondern dass sie auch sofort wissen, wie die Doku geschrieben wird, weil es überall im Unternehmen gleich gemacht wird.
Und dass die Doku auch überall gleich aufgebaut wird.
Das heißt, wenn ich das Team wechsle, dann muss ich mich nicht erst an die neue Struktur der Doku gewöhnen, weil dieses Team anders dokumentiert hat, sondern ich weiß genau, wo ich alles finde, weil es ist genau dieselbe Struktur, die ich in meinem alten Team auch hatte.
Also das, ja, man wird da ab, ja, ab einer gewissen Größe ist es im Grunde unumgänglich, sich einmal wirklich hinzusetzen und zu sagen, wir überlegen uns jetzt, wie wollen wir das aufziehen, was sind unsere Anforderungen.
Und von da kann man natürlich weitermachen und dann vielleicht einfach sagen, so ja, einmal im Jahr oder alle zwei Jahre machen wir nochmal so ein kleinen Workshop, so zwei Tage oder so, und oder einfach nur irgendwie eine Woche, wo wir zwei, drei Meetings haben, wo wir nochmal reflektieren und evaluieren.
Funktioniert das alles so oder müssen wir wirklich ein neues Tool einführen oder da nochmal das ganze Größe aufziehen.
Aber initiell wird man einmal, genauso wie man bei der Software auch initiell einmal sich wirklich hinsetzen muss, sich die Architektur überlegen muss, muss man es bei Doku im Grunde auch machen, einmal, ja.
Das ist ja eigentlich auch eine sehr gute Begründung, warum offene Standards auch bei Dokumentation sinnvoll sind.
Sowas wie ARC 42 oder C4, dann kennt man sich in der Navigation der Diagramme oder der Architekturdokumentation schon aus, wenn jeder sich an diese Standards hält und man braucht sie nicht erst noch zu entwickeln.
Daniel Pisano schreibt noch, wer kennt den Spruch nicht, wenn X wüsste, was X weiß, ja, das ist die Auffindbarkeit der Dokumentation.
Wie oft habe ich schon irgendwie früher auf Google nach Antworten gesucht und meine eigenen Stack Overflow-Posts gefunden.
Oh ja.
Ja, so ist das.
Oh, hier kriegen wir noch ein Feedback beste Folge, die ich bisher gesehen habe bei euch.
Ja, das ist natürlich sehr gut.
Toll so ein Feedback zum Ende zu bekommen.
Liam, danke, dass du da warst.
Danke, dass du dich meine Fragen gestellt hast, dass du deine Erfahrungen mit uns geteilt hast.
Und ja, dann allen Zuhörern, wenn Sie es jetzt gesehen haben, ein schönes Wochenende.
Ansonsten viel Spaß.
Dann bei der nächsten Folge.
Ich weiß gar nicht, was wir als nächstes Thema haben.
Es wird wieder spannend sein.
Schönes Frau.
Ja, vielen Dank, dass ich hier sein durfte und auch schönes Wochenende von mir.
Genau.
Bis dann.
Ciao.