Der nachfolgende Text wurden mit KI erstellt und kann Fehler enthalten. Fehler gefunden? Bei GitHub editieren
Ja, hallo und herzlich willkommen zu einer neuen Folge von Software-Architektur im Stream.
Heute mit Liam Bergh.
Wir haben das Thema agile Dokumentation.
Liam, stell dich mal kurz vor.
Ja, mein Name ist Liam Bergh, 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, das sind 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 grundsätzlich nicht, wenn Doku so ist, aber im agilen Kontext ist es, gerade wenn man darauf ausgelegt ist, 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 Grenning, einer der Unterzeichner des agilen 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 kamen, musste auch so ein bisschen diese Herangehensweise an Dokumentationen 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 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 mal ganz frech zurückantworten, das heißt Working Software over Comprehensive Documentation.
Danke für die Korrektur.
Ja, also zum einen natürlich wird gesagt, funktionierende Software ist wichtiger oder ist 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 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 lasst 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 investiere lieber in die Software.
Also ich muss sagen, ich glaube, ich bin da immer 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 etwas 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 funktioniert und hat ein Erfolgserlebnis.
Bei der Dokumentation dauert es im Zweifelsfall sehr lange, dass man da Ergebnisse sieht, dass vielleicht Kollege, Kollegin dann kommt und sagt, hey, 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, viele haben gerne Dokumentation, möchten sie aber trotzdem nicht schreiben.
Ich habe auch gerne eine aufgeräumte Wohnung, aber deswegen räume ich nicht gerne auf.
Am Ende hat man gerne Dokumentation, aber darum kümmern ist halt immer etwas.
Das ist einfach dann auch so ein bisschen, glaube ich, teilweise, wie soll ich das sagen, dass die Herangehensweise fehlt, dass man einfach nur weiß, Dokumentation ist wichtig, aber dass es halt nichts Greifbares ist 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 Überforderung, 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 und der Code ist nie fertig, also kommt man auch nie zur Dokumentation.
Was wäre da so dein Ansatz, was würdest du empfehlen als Vorgehensweise?
Erstmal würde ich da jetzt schon so ein bisschen munieren, 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 da geht das dann schon zum Beispiel rein, dass ich sagen würde, überlegt euch, wer die Zielgruppe ist, weil 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 dem Programm nachher arbeiten sollen, die das weiterentwickeln sollen, die brauchen ja auch eine gewisse Dokumentation.
Da 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 Installationsdokumentation, Admin-Dokumentation.
Also da wäre halt für mich der erste Ansatz, sich zu fragen, okay, was für eine Art von Dokumentation brauchen wir überhaupt konkret für uns?
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 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 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 daran 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, 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 Entwickler-Dokumentation, da wäre jetzt meine erste Frage, okay, gibt es da also nie Onboarding oder Offboarding?
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, 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 allein schon, wenn man innerhalb des Unternehmens in Teams wechselt, dann hat man ja dasselbe Onboarding-Problem.
Oder 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 darauf bestehen, sie brauchen keine Doku, ja, dann würde ich da jetzt auch nicht unbedingt anfangen, ich 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 Code schreibe und vier Wochen später reingucke, denke ich mir, wer hat denn den Mist geschrieben?
Und dann gucke ich in 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 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 mehr.
Ich würde jetzt allerdings, das ist jetzt natürlich vielleicht nicht gerade sinnvoll oder 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, 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 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 Sachen 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-Dokumentationen, wenn da eine Variable namens Counter deklariert wird und als Kommentar dann Fehler dran steht oder so was, oder The Counter ist nicht wirklich hilfreich.
Hast du da Tipps und Tricks, wie man irgendwie das zielgruppenorientierte aufbauen kann, dass man sinnvolle Dokumentationen 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 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 Dokumentationen 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 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?
Dann ist auch das Tooling ganz wichtig.
Zum einen ist es das Tool, das man benutzt, falls man wirklich Tools benutzt.
Ich möchte den Begriff etwas weiter fassen.
In dem Sinne geht für mich jetzt auch ein Tool und auch eine Entwicklungsumgebung, dass man sich auch überlegt, dass wir das richtige Tool auswählen zur Dokumentationserstellung.
Zum einen, dass der Output in einer Form ist, wo er von der Zielgruppe auch konsumiert wird.
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, das sind EntwicklerInnen, dann sollte der Output vielleicht in Form einer Readme oder sowas direkt in ein Git eingebunden werden können.
Gleichzeitig dann eben auch fragen, wer soll die Doku denn schreiben?
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 Dokumentationen schreiben, dann wäre es meines Erachtens zum Beispiel eine gute Idee.
Meine Erfahrung ist, dass sowas wie Conference oder so meistens nicht so gut ankommt.
Wenn man aber sagt, hey, kannst du in der Readme das vielleicht ändern?
Und das ist halt was, was die 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 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 einen 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 Docs as Code mäßig schreiben.
Keine Ahnung, die Anwenderdoku, 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 eine und dieselbe Person die Doku schreiben soll.
Weil das löst auch, habe ich festgestellt, 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 meine, dass das Tooling da auf alle beteiligten Zielgruppen passt.
Wir haben die ersten Kommentare hier bei uns im Feed.
Daniel Pisano, Doku aus der Audithölle namens A-Spice.
Da wird es zäh, wenn man das agile macht.
Kennst du A-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.
Deinen Blick entnehme ich gerade auch, 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, wie viel Dokumentation braucht man?
Das kriegt man ja auch vielleicht über die Abdeckung beim Testen mit.
Das Maß, wie viel Dokumentation, gerade im Agilen, ist ja jetzt echt ein Punkt.
Vor allem, man möchte ja auch nicht veraltete 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?
Erst mal ist es jetzt natürlich schwierig, pauschal eine Antwort zu geben.
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 das im Grunde auch agil angeht und iterativ aufbaut.
Das heißt, man guckt erstmal, was ist bei uns der größte Pain Point, wo die meisten an Bord sind und sagen, wir brauchen Dokumentation.
Und sich da dann erstmal auf diesen Punkt fokussiert und sagt, okay, wir bauen das jetzt erstmal auf, sodass wir ein kleines Inkrement an Dokumentation haben und überlegen uns dafür eben auch, wie wir das in unsere vorhandenen Arbeitsprozesse mit einbinden, dass wir die Dokumentation auch regelmäßig pflegen.
Gibt es Möglichkeiten zur Automatisierung?
Und wenn das funktioniert, dass man dann vielleicht auch wirklich in den Retrospektiven, wenn man jetzt nach Scrum das zum Beispiel 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 Frustrationen, weil Leute sagen, ich weiß gar nicht, warum ich das schreiben soll?
Und dass man vielleicht auch irgendwann sagt, okay, damals brauchten wir in dem Bereich Doku, aus welchen Gründen auch immer, es hat sich jetzt was geändert.
Wir müssen das vielleicht auch nicht mehr mit dokumentieren, aber dass man, wie gesagt, erstmal so ein kleines Inkrement, wenn man es erstmal schafft und dann immer weiter durchreflektieren guckt, okay, brauchen wir noch mehr Doku?
Sollen wir da noch was dazunehmen?
Müssen wir vielleicht auch die Prozesse wieder anpassen?
Passt vielleicht das Tooling auch nicht mehr, das wir vor fünf Jahren mal gekauft haben, weil es wirklich gut war?
Aber es haben sich bei uns in der Firma so viele Sachen verändert, dass wir da jetzt einfach was anderes brauchen.
Und dass man sich langsam rantastet und auch immer wieder eben guckt, ist das, sage ich mal, vom Pflegeaufwand her noch in Ordnung?
Oder entsteht da auch viel Frust bei den MitarbeiterInnen, die sagen, ich weiß gar nicht, warum ich das schreibe?
Auf der anderen Seite 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, ja, das sollten wir vielleicht auch noch in Zukunft dokumentieren?
Und dann das langsam so aufbaut und es wird halt, ne, würde ich mal sagen, wie das beim Agilen so typisch ist, es ist halt eigentlich, man ist nie fertig, sondern irgendwann kommt man an einen Punkt, wo man dann wahrscheinlich immer so ein bisschen austarieren muss.
Du hast jetzt öfters mal das Wort Prozesse 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.
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 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.
Also Prozesse sind ja, finde ich, eher in Ablaufdiagrammen oder sowas besser festgehalten als reinen Text.
Das heißt, ab einer gewissen Größe wird man wahrscheinlich nicht drumherum kommen, das irgendwo schriftlich festzuhalten.
Aber ich würde auch da einen sehr schlanken Ansatz verfolgen, weil, wie ich gerade sagte, die Idee ist, es ist etwas, wo man kontinuierlich ein bisschen dran dreht.
Und wenn man dann sagt, allein jetzt die Dokumentation für den Prozess der Dokumentation anzupassen, wird jetzt schon wieder einen halben Tag in Anspruch nehmen.
Das kann halt nicht das Ziel sein.
Also agil umsetzen.
Du hast jetzt auch davon gesprochen, 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.
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 konkreten technischen Dokumentator oder technische Dokumentatorin angestellt hat, 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, die Teams dokumentieren für sich selber, würde ich sagen, es ist auf jeden Fall eine Teamaufgabe.
Ich denke, es hängt vielleicht ein bisschen vom Team ab, ob man so sagt wie bei Scrum, 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, wenn man in einer Retrospektive feststellt, das klappt so mit der Doku nicht, 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 Ansprechpartnerin ist, dann wird es nicht so schwer sein, dafür den Verantwortlichen und die Verantwortlichen 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, 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, genau wie auch das Software-Inkrement im Agilen, dass die Doku dem ganzen Team gehört, vom ganzen Team gepflegt wird und auch vom ganzen Team genutzt wird.
Dass man nicht sagt, wir haben einen, 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 Dokumentations-Sprints.
Macht das Sinn oder wie sollte ich das Ganze angehen?
Dokumentations-Sprints.
Wahrscheinlich gibt es eine differenziertere Betrachtung.
Ich würde allerdings pauschal eher davon abraten.
Die Idee von einem Sprint ist ja auch, dass man am Ende was Fertiges hat, was man präsentieren kann, was nicht nur Selbstzweck ist.
Jetzt ist Dokumentation zwar kein Selbstzweck, aber es bringt ja das Produkt, an dem man arbeitet, nicht voran, wenn man einen Dokumentations-Sprint hat.
Funktionierende Software über umfassende Dokumentation.
Das widerspricht diesem Ansatz.
Wenn man an dem Punkt ist, wo man sagt, es besteht eine Notwendigkeit für einen reinen Dokumentations-Sprint, dann ist das ja nur Symptom eines ganz anderen Problems.
Nämlich, dass die Dokumentation eben nicht schon im gelebten Alltag gepflegt wird, sondern dass es immer noch was Nachgelagertes ist.
Ich muss auch sagen, ich habe das einmal miterlebt.
Wir haben einmal in einem Team, wo ich war, einen Dokumentations-Sprint gemacht.
Fazit war, wir haben fast keine Story fertigbekommen in diesem Sprint.
Am Ende des Tages sind Punkte natürlich relativ, aber es sind über 70 Punkte gewesen, die wir dann in die nächsten Sprints mit reingezogen haben und dann über Wochen wieder abgearbeitet haben.
Das war ein absoluter Flop dieser Dokumentations-Sprint.
Das hat dann auch die anderen Teams davon überzeugt, das bei sich anders zu machen.
Es hört sich danach an, dass ihr da viel technische Schuld aufgebaut habt.
Du hast jetzt gesagt, dass die Dokumentation nicht zu Featuren beiträgt, aber trägt sie nicht zum Werterhalt der Software bei?
Hoffentlich.
Ich habe die Meinung, dass Dokumentation ohne die Software wertlos ist, weil Dokumentation nur im Kontext der Software funktioniert.
Die Software im Zweifelsfall kann ihren Job auch tun, ohne dass die Dokumentation existiert.
Dokumentation ist immer an die Software gekoppelt.
Im Grunde ist der Wert der Dokumentation von der Software abhängig.
Deswegen ist es auch ein sehr guter Ansatz, zu sagen, funktioniert die Software über umfassende Dokumentation?
Im Endeffekt kann ich wieder auf den Punkt zurückkommen, den ich vorher gesagt habe.
Wenn man an diesem Punkt ist, wo man sagt, wir lassen uns einen Dokumentations-Sprint machen, wir haben so viel Doku noch zu schreiben.
Es kann vielleicht für manche Teams funktionieren.
Ich will jetzt nicht pauschal sagen, das wird nie funktionieren.
Ich kann mir nicht vorstellen, dass es in der Regel funktioniert.
Eigentlich ist es auch nur ein Symptom für ein anderes Problem.
Dann wäre vielleicht eher der Ansatz, zu sagen, 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 in unserer Arbeitsweise aktiv ändern, dass sich nicht wieder so viel ansammelt.
Weil Dokumentation nicht nachgelagert irgendwann später passieren sollte.
Was ist jetzt dein konkreter Vorschlag?
Wie baue ich das in die agile Arbeitsweise ein, damit sich nichts ansammelt?
Ein Ansatz kann zum Beispiel sein, genauso wie man sagt, Software wird erst geschrieben, dann wird sie getestet, dann kommt eine Code Review und dann erst wird die Neuentwicklung auf den Main Branch gemerged.
Dass man da genauso konkret sagt, in diesen Schritten ist dazwischen auch noch ein Schritt, dass die Doku geschrieben wird, dass man wirklich sagt, das gehört fest mit rein, dass man dementsprechend auch sagt, dass jedes Ticket zur Definition gehört, dass die Dokumentation geschrieben ist.
Es ist natürlich auch immer die Frage, wie man Tickets schneidet und worüber Tickets sind.
Manchmal gibt es halt auch einfach Tickets.
Das war zum Beispiel bei uns auch ein Diskussionspunkt, ob man das bei Bug-Tickets auch machen muss.
Die Idee, wo wir uns darauf geeilt haben, war, bei einem Bug-Ticket muss keine Dokumentation angepasst werden, weil die Dokumentation, außer man hat jetzt technisch eine große Änderung gemacht, aber bei den kleinen Bug-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.
Dann ist die Dokumentation ja schon richtig, sie muss also nicht mehr angepasst werden.
Das heißt, es kommt dann vielleicht auch wieder darauf an, was ist 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 zum einen natürlich guckt, was automatisiert werden kann, aber allein schon im Bereich der Doku, dass man aber vielleicht auch da beim Git dann irgendwie eine Überprüfung reinmacht, dass gesagt wird, hey, also gerade wenn die Doku auch verheiratet ist mit dem Git, dass man sagt, hey, ich sehe, es wurde nichts, was hier zu diesem Pull-Request gehört, da wurde nichts in das Doku-Projekt gepusht.
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, das wären jetzt so die Ansätze, wo 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.
Gerade wenn ich den Tool-Herstellern Glauben schenken darf, dann kann ich ja jetzt mit Gen-AI einfach meine 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?
Jein.
Also ich glaube, du hattest da auch vor kurzem einen Post drüber bei LinkedIn, auf dem ich tatsächlich auch kommentiert habe.
Und im Grunde, ja, Gen-AI kann Teile der Dokumentation wirklich übernehmen, gerade wenn es so um Code oder sowas darum geht, den Code einfach oder 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 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 zweitmal 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 in Zukunft, wenn die KI alles übernimmt, dann brauchen wir ja überhaupt keine Dokumentation mehr.
Ich würde der 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 liest sich das gesamte Programm durch und dann hat die alles 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 ressourcenschonender, eine Doku zu haben, die die KI liest und an der sie dann sich langhangelt, um dann Erweiterungen im Code zu machen.
Da kann ich jetzt aber keine realistische Einschätzung abgeben, ob das wirklich am Ende ressourcenschonender 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 wir den aus dem Entwicklungsprozess rausnehmen, haben wir vorne einen 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 war für mich jetzt die Implikation, zumindest die KI ist 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 Readmes 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 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, wo du das jetzt gerade sagst, 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.
Je nachdem, wie tiefgreifend die Tickets sind, 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, das kann man jetzt pauschal nicht beantworten.
Innerlich kriege ich ein bisschen nervöses Augenzucken, wenn du sagst, wir schreiben das auf dem Whiteboard und danach wischen wir es wieder ab.
Ich denke mir, ihr könntet wenigstens ein Foto davon machen.
Man muss halt die richtige Form für sich finden, das richtige Vorgehen.
Ich würde sagen, es gibt bei AG nicht die eine richtige Art und Weise zu dokumentieren.
Und es kommt dann im Zweifelsfall echt aufs Tooling an.
Aber wie gesagt, Tickets sind auch schon Dokumentation.
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 einen Satz draufschreiben.
Ja, aber selbst das dokumentiert 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 – einfach um jetzt nochmal so kurz die Leute abzuholen, die das vielleicht noch nicht gehört haben – C4 hat mit Diagrammen viel zu tun.
Das ist ein Ansatz für Softwarearchitekturdokumentation.
Und C4 hat zum einen die Grundidee, zu sagen, wir haben feste Abstraktionsebenen.
Deswegen heißt es C4, weil es vier verschiedene Abstraktionsebenen gibt, wobei das eigentlich auch so ein bisschen aufgeweicht ist.
Die erste ist System Context, wo man einen Überblick bekommt über das Softwaresystem, um das es geht.
Dann hat man Container-Ebene, wo man einen Überblick bekommt.
Container ist nicht Docker, ganz wichtig, sondern das ist einfach nur die Vokabel, die gewählt wurde.
Das heißt, ein Softwaresystem besteht aus mehreren Containern und Container-Ebene ist, wo man dann einen Überblick über Container bekommt, über einzelne.
Dann gibt es die Komponenten-Ebene oder Component.
Das ist dann die nächsttiefere Ebene.
Also ein Container besteht aus mehreren Components oder kann aus mehreren Components bestehen.
Und nach der Komponente käme dann der Code.
Und das ist die vierte Ebene.
Da wird dabei in der Regel gesagt, wenn es nicht automatisiert ist oder es 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 mit den vier Ebenen so ein bisschen relativ.
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, Softwaresystem.
Das sind so feste Vokabeln.
Die sind klar definiert, dass die Leute auch wirklich von derselben Sache reden.
Wenn ich jetzt ohne eine klare Definition einfach sagen würde, ja, hier die Komponente, dann könnte ich von einer ganzen App reden.
Dann könnte ich auch nur von einer UI reden.
Dass man einmal feste Definitionen hat für verschiedene Vokabeln.
Wie gesagt, das Wichtige sind Component, Container, Softwaresystem.
Dann gibt es natürlich auch 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.
Wir können uns verständigen, weil wir ein festes Vokabular haben.
Wir haben verschiedene Abstraktionsebenen.
Dann kommt auch wieder dieser Punkt Zielgruppenorientierung mit rein, weil nicht jede Abstraktionsebene für jede Person relevant ist.
Die Projektleitung muss nicht wissen, was auf Code-Ebene passiert.
Oder 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.
Wenn man jetzt Microservices hat, was es da für einzelne Microservices 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 Softwarearchitekt oder Softwarearchitektin 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.
Deswegen ist die Idee gewesen, wir machen einmal eine Draufsicht.
Die ist eher für nicht technische Akteure.
Dann gehen wir ein bisschen weiter in die Tiefe.
Wenn man einen technischen Hintergrund hat und technische Informationen braucht, dann haben wir 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 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übersicht nehmen.
Dann ist es auch für mich als Entwicklerin interessant.
Im Endeffekt läuft es aber darauf hinaus, 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 zeigen dann wirklich die Infrastruktur, auf der die Architektur läuft.
Ich glaube, die heißen sogar Infrastruktur-Diagramme.
Das ist dann zum Beispiel eben auch für so die DevOps-Gruppe interessant, für die Leute, die wirklich die Infrastruktur bereitstellen.
Es läuft immer wieder darauf hinaus, 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 denke nicht, dass es mit dem agilen Ansatz im Kopf direkt entwickelt wurde.
Es ist jetzt nicht gezielt für den agilen Ansatz entwickelt.
Das funktioniert grundsätzlich, aber ich würde sagen, es harmoniert sehr gut mit dem agilen Ansatz, weil eben wirklich die Idee ist, wir teilen es so auf, 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.
Diagramms as Code 2.0 nennt Simon Brown das ja, glaube ich.
Also Diagramms as Code, das ist klar, die Diagramme macht man nicht mit einem grafischen Programm, sondern die werden als Code geschrieben, z.B. plant.uml.
Diagramms as Code 2.0 ist die Weiterentwicklung davon, dass man nicht mehr die reinen Diagramme beschreibt, sondern dass man in einer DSL, in einer Domain-Specific-Language, die Architektur beschreibt.
Dann kann man sich beliebig viele Diagramme daraus definieren und daraus ableiten.
Man hat eine Single Source of Truth, an der man nur noch Veränderungen vornehmen muss und alle Diagramme, die daraus generiert werden, die aktualisieren sich automatisch.
Dadurch hat man dann auch wieder sehr wenig Pflegeaufwand und dadurch, dass es eben auch in Form von Code ist, sind wir wieder beim Tooling.
Dann können auch die Leute, weil tendenziell 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.
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 viel Aufwand sein und man kann es einfach spontan, schnell und einfach ändern und es damit, 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 her, ändere in dieser DSL, in dem Modell und lasse mir die Sichten darauf generieren, was dann ja tatsächlich den agilen Prozess sehr schön unterstützt ist.
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.
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.
Es ist eine sehr simple Sprache eigentlich.
Ich glaube, das Schwierigere ist eher, erstmal den ganzen Ansatz von C4 zu verstehen und sich wirklich einmal 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 Coding-Erfahrung hat, und das richtet sich ja im Grunde an Programmierende, sehr schnell zu lernen.
Ich hatte das durch jeden Unternehmen 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 habe denen dann ein, zwei Code-Beispiele gezeigt.
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 Software-Systeme mit Containern und Components komplett selber zu erstellen, weil es sehr intuitiv ist.
Wenn man schon mal mit Code gearbeitet hat, ist da wirklich die Lernkurve nicht so steil.
Okay, das hört sich ja gut an, aber man muss das Tooling aufsetzen.
Aber wenn man in der Softwareentwicklung ist, dann hat man ja Spaß daran, das Tooling aufzusetzen.
Dann geht das ja.
Ich hoffe es.
Das ist tatsächlich das Einzige, wo ich sagen würde, das ist vielleicht eine Hürde, da wirklich ein Tooling zu finden.
Man kann den Structurizer nehmen.
Ich weiß nicht, ob sie jetzt offline genommen wurde.
Irgendwas wurde offline genommen beim Structurizer.
Es gibt irgendwie eine Cloud-Lösung, glaube ich, oder so eine Art Cloud-Lösung.
Structurizer ist das Tooling von Simon Brown für C4.
Ich bin mir nicht mehr sicher.
Wie gesagt, irgendwas davon wurde offline genommen.
Es gibt auch tatsächlich Open-Source-Projekte, die einem auch helfen, wenn man nicht diese Cloud-Lösung möchte oder diese Enterprise-Lösung, dass man das bei sich…
Zum Beispiel, wir hatten das dann so, oder wo ich C4 eingeführt habe, die haben dann auch eine Open-Source-Lösung genommen, sodass man erst mit dem Structurizer alles schreibt, aber dann halt nicht das in eine Cloud lädt oder so, und das dann über den Structurizer darstellen lässt, sondern dass es dann einfach in der Git-Pipeline ein anderes Tooling eingebunden wird.
Ich weiß gerade gar nicht mehr, wie es heißt.
Und dann wird einfach eine Webpage erstellt.
Da hängt dann wieder ein Plant-URL mit drin.
Dann wird das alles mit einem Plant-URL umgewandelt, und dann hat man einfach eine Webpage, die man selber hosten kann und ist dann nicht auf ein externes Tool angewiesen.
Und wenn man 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 zusammenfassen kann.
Du hast jetzt gesagt, dass Dokumentation im Agilen auf jeden Fall nicht wegfällt, sondern nur bei 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, das auf jeden Fall in jeder Story, das eben genauso wie das Testen zum Fertigstellen der Story gehört, dass Tooling wichtig ist, dass unterschiedliche Elemente wichtig sind, dass es eben nicht nur einfach plain Text ist, sondern dass eben auch Diagramme wichtig sind und auch, dass die Automatisierung wichtig ist, dass man die Dokumentation so splank 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 Dokumentations-Sprints machen muss.
Das fasst so eigentlich ganz gut zusammen, wie wir agil Dokumentation machen können, oder?
Ja.
Ich würde sagen, das ist 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 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, weil irgendjemand das entschieden hat, und Dokumentation hat eigentlich keinen 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 wichtigste 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 zeigt, guck mal, ihr habt gar keine Onboarding-Dokumentation, das ist jetzt ein Problem?
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.
Es ist halt die Frage, wenn man jetzt wirklich sagt, ich will meine KollegInnen überzeugen, da würde ich jetzt halt, 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, würde ich einfach sagen, okay, ist es dir nicht auch schon mal passiert, dass du irgendeinen Fehler gesucht hast und dann hast du nach fünf Stunden Debugging gemerkt, oh, das ist eigentlich gar kein Fehler, wir haben nur vergessen zu dokumentieren, dass das eigentlich geplante Verhalten war?
Ich hätte den Fehler viel schneller gefunden, wenn ich es einfach mal dokumentiert hätte.
Dieser Spruch, so stundenlanges Debugging kann einem fünf Minuten Lesen der Dokumentation ersparen.
Dass man da vielleicht auch einfach mal versucht, ein Bewusstsein zu schaffen, wann hast du das letzte Mal an einem Ticket gesessen und hast dir nach drei Stunden Debugging gedacht, boah, wenn ich das vorher gewusst hätte, dann hätte ich mir hier sehr viel Zeit sparen können.
Oder auch einfach, ich weiß nicht, inwiefern das dann in solchen Fällen ein reales Problem ist, wenn das Team wirklich komplett sagt, ja, wir wissen das alles.
Meine Beobachtung in der Realität ist, dass man häufig ein, zwei Kollegen hat, die wirklich im Grunde alles oder sehr viel wissen und dass die dann häufig sehr oft gefragt werden, pass mal auf, du weißt doch, wie das geht, kannst mir das gerade nochmal erklären, weil ich habe hier so ein Ticket.
Und dass die dann sehr viel Arbeitszeit nicht mit tatsächlicher Arbeit verbringen, sondern damit anderen Leuten Dinge zu erklären, weil sie nicht dokumentiert sind.
Und dass man da auch sagt, hey, willst du nicht auch manchmal einfach gerne nur eine Stunde lang einfach ungestört programmieren, ohne dass jemand fragt, ohne dass jemand Fragen hat, ohne dass du jemandem was erklären musst.
Du könntest die Leute, wenn wir Doku hätten, dann einfach auf die Doku verweisen und sie würden irgendwann hoffentlich aufhören, dich ständig zu fragen.
Da fällt mir noch so eine eigene Story ein, dass ich mal jemanden gefragt habe, der ein sehr gutes technisches Blog hatte, wo er die Zeit hernimmt, diese ganzen Blogbeiträge zu schreiben.
Und genauso wie du es jetzt gesagt hast, hat er mir eigentlich geantwortet, das spart ihm Zeit, weil immer wenn irgendwie eine Frage reinkommt, dann beantwortet er nicht die Frage, sondern dann schreibt er darüber einen neuen Blogartikel, verweist dann auf diesen neuen Blogartikel und weiß, dass er diese Frage hoffentlich nicht mehr reinbekommt, beziehungsweise wenn sie reinkommt, er auf diesen Blogartikel verweisen kann.
Das finde ich eigentlich einen sehr guten Ansatz, um loszulegen, oder?
Immer wenn man merkt, da ist irgendwo eine Frage, dass man mal guckt, haben wir eigentlich Dokumentation dazu?
Wenn nicht, dann lasst ihr uns schreiben, oder?
Damit wird man doch ganz gut agil anfangen können, um eben langsam die Dokumentationsbasis zu verbessern.
Ja, 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.
Man bekommt dann eine Frage und denkt sich, das sollte ich mal irgendwo hinschreiben.
Im schlimmsten Fall hat man dann irgendwie ein Confluence oder so und sagt dann, ich erstelle hier irgendwo eine Unterseite und die findet dann nachher auch keiner wieder.
Dann hat man das Problem eigentlich nicht gelöst.
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, da eine Ordnung reinbringen.
Danach kann man dann natürlich wieder, ja, da füge ich hier noch was hinzu, aber man sollte da eine Grundstruktur erstmal haben.
Das ist ein guter Punkt, der kommt hier auch gerade im Chat rein, als Kommentar von Deremder.
Wichtig ist auch die Auffindbarkeit der Dokumentation, klare, einheitliche Struktur.
Wenn man die nicht hat, ist es Write-only-Dokumentation.
Sie wird geschrieben, aber nicht gelesen.
Ich kenne das auch so, dass 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 sich am Anfang Gedanken macht, was für Doku man braucht, dass man auch die Struktur aufbaut, oder?
Genau, das ist vielleicht eine bittere Pille zu schlucken, weil das, 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, wo 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 einmal muss man da wirklich in den sauren Apfel beißen und sagen, wir stecken jetzt Arbeit da rein.
Ob man das jetzt als Dokumentations-Sprint 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 Ä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 man wird da 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 einen kleinen Workshop, so zwei Tage oder so, 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ößer aufziehen, aber initial wird man einmal, genauso wie man bei der Software auch initial 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 meinen 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ß bei der nächsten Folge.
Ich weiß gar nicht, was wir als nächstes Thema haben.
Es wird wieder spannend sein.
Vielen Dank, dass ich hier sein durfte und auch ein schönes Wochenende von mir.
Bis dann.
Ciao.