Der nachfolgende Text wurden mit KI erstellt und kann Fehler enthalten. Fehler gefunden? Bei GitHub editieren
Hallo und herzlich willkommen zu einer neuen Episode von Software-Architektur im Stream.
Wir haben heute die letzte Episode für dieses Jahr und ich hoffe und glaube, dass sie ziemlich cool und besonders wird, weil heute ist Ralf Müller bei uns zu Gast.
Hallo Ralf.
Hallo Lisa.
Und die Einladung zu diesem Stream basierte auf einer, ich sage mal, hitzigen Diskussion, als damals Falk Sippach mit mir über Architektur-Dokumentation gesprochen hatte.
Und da dachten wir, wir ergreifen die Chance, schnappen uns Ralf und sprechen mal mit ihm über Architektur-Diagramme und über Architektur-Dokumentation.
Genau.
Und wir freuen uns auf jeden Fall riesig, wenn ihr auch Fragen stellt und vielleicht auch Kommentare liefert.
Es kamen schon ein paar Sachen im Vorfeld, aber genau, das ist so viel zur Einleitung.
Jetzt geht es hier wirklich los.
Genau.
Hallo Ralf.
Erstmal, wer bist du und was machst du so?
Ja, Ralf Müller mein Name.
Wer bin ich?
Was mache ich?
Ich finde die Frage immer schwer zu beantworten.
Ich bin als Chef-Architekt bei der DB Systel, dem IT-Partner der Bahn, eingestellt und kümmere mich da um alle möglichen Probleme, aber vor allem um mein Steckenpferd Architektur-Dokumentation.
Wie bist du da rangekommen?
Also was hat dich bewogen, dich für Architektur-Dokumentation zu interessieren?
Ja, das war, dass ich eben lange Jahre als Entwickler gearbeitet habe und gemerkt habe, irgendwie will ich auch mal das Große und Ganze verstehen und habe mich dann eben an die Architektur rangewagt, an die Definition, was ist eigentlich Architektur.
Ich habe gemerkt, dass Architektur eben viel Kommunizieren und Dokumentieren ist und Kommunizieren über die Dokumentation und habe dann gemerkt, dass Dokumentieren mit Textverarbeitung und Co. nicht so wirklich Spaß macht, weil man kriegt zwar einen schnellen ersten Wurf hin, aber dann das Ganze aktuell zu halten, ist dann doch etwas schwieriger und habe dann angefangen, mich damit zu beschäftigen.
Wie kann ich es besser machen?
Wie kann ich mit Skripten z.B. aus meinem UML-Tool die Diagramme rausziehen und automatisch in meine Dokumentation einbetten?
Und so bin ich dann zum Docs-as-Code-Ansatz gekommen und arc42 und seitdem baue ich das immer weiter aus, dass es immer leichter wird, eben dieses Gespann zu nutzen.
Was waren die ersten Tools, mit denen du dokumentiert hast, also bevor du zu dem Docs-as-Code-Tool-Ansatz kamst?
Ja, das ist also, was man halt so kennt, die normale Textverarbeitung, was natürlich dann immer irgendwie zu einer seitenorientierten Dokumentation führt, wo man dann immer auch die Probleme hat mit irgendwelchen Verweisen.
Und wenn man dann auf ein Kapitel in einem Dokument hinweisen möchte, dann verschickt man das ganze Dokument und sagt, du, in dem und dem Kapitel, das passt irgendwie nicht so gut.
Wikis, ja, gab’s auch damals schon und als ich damit angefangen habe, waren da ein paar Features noch nicht vorhanden, haben aber natürlich Vorteile, weil man da eben direkt auf irgendwelche Abschnitte verlinken kann, was natürlich da mit Sachen Diagrammen immer so ein bisschen schwierig ist.
Wie gehe ich da mit Diagrammen um?
Erstelle ich die in einem externen Tool, lad die dann hoch und wenn ich’s dann hochgeladen habe, genauso wie bei einer Textverarbeitung, wenn ich da irgendwie was per Copy & Paste reingespielt habe, wenn sich dann das Diagramm irgendwie ändert, dann muss ich mich wieder dran erinnern, wo hab ich’s überall per Copy & Paste reingebracht, wo muss ich’s aktualisieren?
Und das wird dann mit der Zeit ziemlich aufwendig und das führt dann eigentlich meistens dazu, dass man es eben leider doch nicht aktualisiert.
Ich muss auch gerade, also ich hab gerade einfach so, Flashbacks ist auch zu viel gesagt, aber ich muss gerade so an den Enterprise Architect denken, wo da nur eine Handvoll ausgewählter Personen Zugang zu diesem sauteuren Tool hat, was kaum einer bedienen kann und die sind dann alle im Urlaub und dann wird diese Architekturdokumentation einfach nicht angepasst, weil kann halt dann keiner.
Jaja, da sprichst du aber ein sehr schönes Thema an.
Also der Enterprise Architect, der geht ja noch von den Lizenzkosten her, also das ist ja was, wo man tatsächlich jedem Zugriff geben kann, aber die Bedienung ist nicht so ganz einfach.
Andere UML-Tools sind ja tatsächlich so teuer, dass ja nur wenig Leute eine Lizenz haben, dass sie editieren dürfen, aber gerade wenn ich dann eben mit einem Architekturmodell arbeite und man dann sagt, ach komm, hier dieses Modul, das nennen wir jetzt um.
Ich benenne es im Modell um und dann ist die erste Frage, in wie vielen Sichten hat sich das jetzt geändert?
Welche Diagramme, welche Sichten werden in Dokumenten verwendet und wie kann ich das jetzt aktualisieren?
Und das war in der Tat so das erste Skript in meiner Skriptsammlung, die dann zu docToolchain wurde, weil ich eben gesagt habe, irgendwie muss ich diese Diagramme automatisiert rausbekommen und habe es dann geschafft, den Enterprise Architect Headless zu starten, in einem Skript alle Diagramme zu exportieren und wenn ich dann den Docs-as-Code-Ansatz verwende, dann habe ich ja meinen Markdown oder besser noch ASCII-Doc, was diese Images referenziert aus einem Folder.
Das heißt, sobald ich die Images neu exportiert habe und dann die Dokumentation baue, dann habe ich die eben auch in meiner Dokumentation aktualisiert.
Und das ist schon ein ganz großer Schritt nach vorne, weil ich dann jederzeit einfach sagen kann, ist egal, was ich an dem Modell geändert habe, die Sichten werden aktualisiert, exportiert und meine Dokumentation ist in Sachen Diagrammen auf dem aktuellen Stand.
Du hast gerade schon gesagt, die docToolchain, das war eine der ersten Sachen mit dem Enterprise Architect.
Ich frage mich gerade, ob das so war, dass du so deine Skriptsammlung irgendwo rumliegen hattest und irgendwann hast du gemerkt, das ist eigentlich so cool, ich möchte das teilen und dann ist so daraus die docToolchain geworden oder ist das irgendwie anders gekommen?
Ja, es war damals, ich meine so ein Open-Source-Projekt ist ja ziemlich cool, weil man so sein eigenes hat.
Und deswegen habe ich mir eben auch gedacht, diese Skripte, die ich hier habe, warum nicht Open-Source machen und damit auch die Chance haben, dass andere drüber gucken und sie verbessern.
Und die Rechnung ist aufgegangen, also mittlerweile haben wir da relativ viele Kontributoren, die eben tatsächlich das Ganze verbessert haben, die immer mal wieder irgendwelche anderen Use Cases haben und damit zu dem großen Ganzen beigetragen haben.
Dadurch ist die docToolchain eigentlich ein relativ großes Projekt geworden, von dem man aber meistens eben nur einen Ausschnitt sieht.
Also gerade der Static Site Generator oder der Export nach Confluence ist sehr beliebt und andere Module werden dann nicht ganz so tief betrachtet.
Und wir sind ja jetzt beim Diagramm, da ist ja, ja, Diagramme im Docas-as-Code-Ansatz, PlantUML und sowas, ist ja immer nicht ganz so einfach zu handeln.
Und es gibt ja dieses Tool, früher dieses Draw.io, dann Diagrams.net und irgendwie weiß ich jetzt momentan gar nicht, welches der offizielle Name ist.
Aber das ist ja so ein Diagrammeditor, der recht beliebt ist, recht weit verbreitet.
Und das war mit Alexander Schwarz, dass ich mich da unterhalten habe, hey, es gibt für Visual Studio Code da ein entsprechendes Plugin und Alexander Schwarz hatte ja auch das ASCII-Doctor-Plugin für IntelliJ und da habe ich mir gedacht, Mensch, der hat doch sicher das Know-How, wie man da eben entsprechend Diagramms.net-Plugin für IntelliJ macht.
Und in dem Zuge dieses Open-Source-Austauschs kam dann auch noch Henning Dieterichs dazu, der das Plugin schon für Visual Studio Code gemacht hat.
Und dann haben wir zusammen, zu dritt, das Ganze für IntelliJ gemacht.
Und ja, das ist jetzt für IntelliJ das Diagramms.net-Plugin, was jetzt eben auch im docToolchain-Namespace Open-Source liegt.
Lange Herleitung, aber das war jetzt so, weil ich mal loswerden wollte, dass eben das docToolchain vieles umfasst, viele Ansätze und dass gerade dieses Plugin eben jetzt sehr gut hilft, Diagramme besser zu maintainen.
Damit hast du aus Versehen auf eine Frage geantwortet, die wir vorher im Slack bekommen haben, würde ich behaupten.
Und zwar hatte da Kevin Stillhammer gefragt, wie gehst du mit dem Feedback um, dass What-You-See-Is-What-You-Get-Editoren wie Jira, Confluence, Visio intuitiver sind und man mit docToolchain eine unnötige Hürde schafft?
Also, du hast eben einmal gesagt, dass du ja von docToolchain nach Confluence deployen quasi kannst oder veröffentlichen.
Deployen ist vielleicht auch zu viel gesagt.
Und du hast auch gesagt, dass man diese Draw.io oder diagrams.net oder die What-You-See-Is-What-You-Get-Diagrammeditoren mit der docToolchain nutzen kann.
Denkst du denn, dass das Argument häufig kommt, dass docToolchain unintuitiver ist und dass man lieber nur in Confluence und so weiter arbeiten sollte?
Ja, also dieses Argument kommt immer wieder und es kommt immer drauf an, wer mit der Dokumentation arbeitet, wer sie erstellen möchte.
Ich erlebe es bei Techies immer wieder, dass sie den Docs-as-Code-Ansatz lieben.
Sie sind den ganzen Tag in ihrer IDE, möchten die am liebsten gar nicht verlassen.
Und wenn sie dann die Dokumentation auch in der IDE schreiben können, dann sind sie glücklich.
Wikis sind natürlich, da brauche ich mich erstmal nicht großartig einzuarbeiten.
Es ist augenscheinlich die kleinere Hürde.
Ich sage augenscheinlich, weil jeder kennt es eigentlich von Markdown.
Ich schreibe so eine Dokumentation runter wie eine E-Mail.
Und dann merke ich, okay, Überschriften formatieren, ja, ein Heft davor.
Das ist einfach.
Das geht auch in ASCII-Doc.
Und in ASCII-Doc kann ich dann genauso, wie ich in Wikis besondere Formatierungen ausfindig machen kann, kann ich das dann auch in ASCII-Doc.
Und das ist eigentlich die größere Hürde.
Wenn man da irgendwie ein Merge-Request hat oder irgendwelche Merge-Probleme hat, dass man die überwindet.
Aber das ist auch interessant, dass ich viele Teams erlebt habe, die eben auch schon mit ihrer Textverarbeitung nach einem Dokumentenmanagement-System geschrien haben.
Und wenn sie da eines bekommen haben, gesagt haben, oh, das ist aber komplex und das ist unpraktikabel.
Und ich denke, mit Git haben wir als Techies ein Dokumentenmanagement-System, was perfekt ist, was eben die minimale Komplexität mitbringt, die man braucht.
Ja, und mit dem Diagramm What you see is what you get.
Also gerade mit dem Diagramms.net ist das ein schöner What you see is what you get Editor, mit dem ich arbeiten kann.
Und das Tolle ist halt, dass beim PNG- und SVG-Format die Sourcen direkt in dem Format gespeichert werden.
Das heißt, ich habe nur ein PNG in meinem Repository und kann das direkt wieder editierbar öffnen.
Und das ist auf so vielen Ebenen superklasse, weil was mich an vielen Diagrammen stört, ist, wenn man in so ein Projekt reinkommt und fragt, wo habt ihr die Architektur?
Ja, hier, guck mal, ich habe hier ein PDF von so einer PowerPoint.
Und wenn man dann Architekturarbeit leisten soll, dann sieht man da zwar schöne Diagramme, aber es ist teilweise sehr, sehr schwer bis unmöglich, die Quelle der Diagramme ausfindig zu machen und sie dann wieder zu bearbeiten.
Das heißt, man erstellt sie teilweise neu.
Und gerade wenn die modellbasiert sind, dann ist das halt schon ziemlich ärgerlich, weil man dann das ganze Modell irgendwie neu aufsetzen muss.
Und das ist halt bei dem Diagramms.net, wenn ich das Repository kenne, wenn ich das PNG-File habe, dann kann ich direkt damit arbeiten.
Bei PlantUML ist das ähnlich.
Da fällt mir auch gerade so ein Punkt ein bezüglich PlantUML.
Viele Leute sagen, PlantUML sieht so hässlich aus.
Aber ich sage, das ist ein Vorteil.
Das ist ein Vorteil, wenn ich an dem Design erkenne, welches Tool es war, weil ich dann schon weiß, wo ich suchen muss.
Und dann finde ich eben leichter auch die Chancen.
Das ergibt auf jeden Fall Sinn.
Ich hätte eine Nachfrage nochmal.
Du sagtest eben, also genau, ich kenne PlantUML und ich kenne auch Draw.io.
Was ich mich frage, bei PlantUML sehe ich ja in der Git-Historie ganz klar, wo sich was geändert hat, weil das ist ja einfach ein textbasierter Ansatz, um die Diagramme zu beschreiben.
Habe ich dieselben Möglichkeiten, auch wenn ich ein SVG oder einen PNG einchecke, dass ich wirklich das Div visuell sehe und sehe, was hat sich geändert?
Oder habe ich die Chance dann vertan, wenn ich Draw.io einsetze?
Das ist eine sehr gute Frage.
Ja, das ist ein großer Vorteil von PlantUML.
Und das ist halt bei Diagramms.net oder Draw.io nicht so.
Es gibt aber sehr gute grafische Div-Tools für Images.
Wenn man nicht zu viel an dem Diagramm ändert, dann sieht man über so einen Div eben auch optisch, was sich geändert hat.
Meistens ist es dann doch so, es ist selten, dass ich mal irgendwie den Div bei einem Diagramm einsetze.
Wobei bei PlantUML liebe ich es, wenn man mit Sequence-Diagrammen arbeitet und im Team irgendwie so verschiedene Vorschläge vergleichen möchte und dann jedes Teammitglied sich so ein Sequence-Diagramm einfach nehmen kann, ein bisschen verändern kann und man sieht genau, was ist da anders.
An welcher Stelle hat derjenige gearbeitet?
Und für die Zusammenarbeit ist das Gold wert.
Es brutzeln gerade so ein paar Anmerkungen und Fragen über die Chats rein.
Und ich würde dir gerne erst die, ich glaube, PlantUML Anmerkungen vorlesen, weil es nur Anmerkungen sind.
Jendrik Oldmann sagt, PlantUML kann man auch stylen.
Dann sieht es sogar schick aus.
Ach ja, die Namen aussprechen, das ist immer das größte Highlight hier.
Avo Mormos sagt, ich denke, wenn man die Standard 7 plus minus 2 Komponenten-Regel einhält, werden PlantUML-Diagramme auch nicht so unübersichtlich.
Ich glaube, da hat er auch recht.
Und ich glaube, dann sind sie auch noch wartbarer, als wenn man zu viel versucht, in ein Diagramm zu patschen.
Definitiv.
Also gerade das 7 plus minus 2 ist bei PlantUML ganz wichtig, weil ansonsten wird das Ganze schwer wartbar.
Die Sache mit dem Styling, das ja, kann man machen.
Da habe ich aber oftmals das Problem, dass das PlantUML-Diagramm dann mehr Styling-Informationen hat, als überhaupt Diagramminformationen.
Das kann man natürlich auslagern, wird meistens aber, so wie ich das sehe, nicht gemacht.
Und was ich in dem Zusammenhang sehr interessant finde, ist, das wird einem gar nicht so bewusst, aber ich habe einen blinden Kollegen, der auf mich zukam und gesagt hat, er hat PlantUML gefunden und er findet das super klasse, weil jetzt hat er die Möglichkeit, als Blinder für sehende Diagramme zu bauen.
Und das passt dann auch im Umkehrschluss, dass wenn wir PlantUML-Diagramme erstellen, dass die Accessibility höher ist, weil man eben das Diagramm sich auch noch vorlesen lassen kann.
Und wenn man dann eben so viel Styling-Informationen unter Umständen drin hat, wenn es nicht einfach nur ein Include ist, dann macht das diesen Use-Case wieder kaputt.
Ich müsste gerade noch daran denken, ich habe auch gelernt, dass die Tabellen in Confluence sind auch nicht accessible für blinde Nutzer.
Das ist noch etwas, was mir vor einiger Zeit zugetragen wurde.
Da kommen immer noch mehr zu und ich glaube, noch mehr Dinge obendrauf.
Ich glaube, gerade dieser Markdown- oder ASCII-Doc-Ansatz und dann eben PlantUML ist maximal accessible.
Ich gebe dir noch weitere Fragen.
Und zwar hat Thomas Schwert relativ am Anfang geschrieben.
Du hattest von deinem ersten Skript berichtet und du hast den Enterprise Architect Headless gestartet und ihn interessiert.
Hat sich Sparks mal den Ansatz, Enterprise Architect auf diese Weise zu nutzen, geäußert?
Wie soll ich darauf antworten?
Kommt drauf an, ist immer die beliebteste Antwort.
Genau, kommt drauf an, ist die Antwort eines Architekten.
Also nein, ich habe da nichts mitbekommen.
Ich glaube, die Dokumentations-Engine im Enterprise Architect ist mittlerweile besser geworden.
Damals wurde so ein HTML exportiert, mit dem man nur schwer was anfangen konnte.
Aber nein, da habe ich kein weiteres Feedback bekommen.
Apropos damals, seit wann gibt es die Doc-Toolchain eigentlich?
Oh, da müsste ich jetzt lügen.
Ich weiß nicht.
Müsste man mal gucken, welches der älteste Commit ist.
Aber es sind Jahre, einige Jahre.
Genau, ich hatte es noch herausgefunden in einer Projektliste, dass ich irgendwann 2017 mal damit umspielen durfte.
Da ist es auf jeden Fall schon ein bisschen länger da.
Genau, es gibt noch zwei Fragen zu eben dieser docToolchain.
Einmal gibt es, Maximilian Schmidt fragt auf YouTube, gibt es in der docToolchain auch eine Integration für Mermaid?
Das Interessante ist, also mittlerweile unterstützt die docToolchain nicht nur AsciiDoc, sondern auch Markdown und Restructured Text und über Plugins kann man theoretisch noch weitere Markup-Sprachen reinnehmen.
Und dann hängt es an der Markup-Sprache, was die unterstützt.
Und AsciiDoc, das ist das, was ich immer empfehlen würde, unterstützt auch Mermaid.
Und ich empfehle mittlerweile auch, also bei vielen Diagrammtypen muss man theoretisch lokal noch irgendwelche Tools installieren, GraphViz für PlantUML und solche Geschichten.
Und der Kroki-Server, der nimmt einem das Ganze ab.
Und AsciiDoc hat Support für den Kroki-Server, dass ich einfach über zwei Attribute den konfiguriere.
Es gibt einen Public Kroki-Server, den ich natürlich für Projekte nicht einsetzen würde, aber der ist relativ leicht selbst aufgesetzt und darüber werden alle möglichen Diagrammtypen unterstützt und eben auch Mermaid.
Sehr cool.
Thomas Schwert hatte noch die Anmerkung, dass Bitbucket ein grandioses Diff von PNGs eingebaut hat, auf wirklich gute Weise.
Also das scheint sich zu lohnen, das mal anzuschauen, wenn man Bitbucket nutzt.
Und es kam noch die Frage von Hans Pallada42 auf Twitch.
Sieht sehr nice aus.
Ist die docToolchain eher für das Java-Ökosystem gedacht oder kann ich auch Angular und Node-Applikationen, Web-Apps, APIs damit vorsorgen?
Also seit Anfang des Jahres haben wir mit der docToolchain einen Schritt gemacht, um die Technik rauszuziehen aus dem Repository.
Viele dieser Tools und docToolchain wird leider oft auch mit Static Site Generators verglichen, haben die ganze Technik mit im Repository.
Das haben wir jetzt geändert.
Das war nämlich auch immer so die Frage, oh ja, da ist Gradle drin, das ist also nur für Java.
Und jetzt ist da quasi nur noch ein Wrapper im Repository und der schaut, ob Docker installiert ist, ob er ein Docker-Image verwendet oder ob er es lokal im User-Folder installieren soll.
Und mittlerweile gibt es auch ein Kommando get-java, was dann die richtige Java-Version auch noch in den docToolchain-Folder installiert.
Und damit ist es eigentlich unabhängig von der Technologie.
Ist natürlich in einer Technologie in Java umgesetzt, aber ansonsten sollte es unabhängig sein und kann eben für alles Mögliche verwendet werden.
Genau, nochmal, ich gehe gleich darauf ein, noch ein kurzer Rücksprung.
Magst du noch einmal kurz, so ganz kurz sagen, was Mermaid überhaupt ist, falls hier Leute sind, die das noch nicht gehört hatten?
Ja, Mermaid ist ähnlich wie PlantUML, eine Library, die eine textuelle Beschreibung eines Diagramms in eine Grafik umsetzt.
Der große Unterschied ist, dass Mermaid als JavaScript auf dem Frontend eigentlich läuft und PlantUML eher auf dem Backend.
Und dadurch, dass es als JavaScript im Frontend läuft, hat zum Beispiel auch der Kroki-Server ein bisschen mehr Probleme dabei.
Das ist dann ein Companion Docker-Container, der dann, glaube ich, per Headless-Chrome das Image rausholt oder sowas.
Aber es funktioniert.
Und wenn man auf Kroki.io geht, dann sieht man eine ganze Liste von solchen Diagramm-Twists, die alle eben Text nach Diagramm wandeln.
Da gibt es Netzwerk-Diagramme und auch, ich glaube, Vega heißt es.
Vega und Vega-Lite ist für Standard-Diagramme wie Pie-Charts, Balken, Liniendiagramme und sowas.
Sehr gut.
Und jetzt tun wir so, als hätten wir die Anmerkung nicht gehört und wüssten noch, über was es da vorging.
Genau, die Frage mit dem, gibt es das nur fürs Java-Ökosystem?
Ich habe in Projekten die Erfahrung gemacht, dass ganz oft die Dokumentation eines einzelnen Services gar nicht wirklich in diesem Service liegt, sondern dass es einen separaten Git-Ordner, ein extra Git-Repository gibt, wo die Dokumentation drin liegt.
Erste Frage, hast du das auch schon mal so gesehen?
Zweite Frage, was würdest du empfehlen oder was findest du sinnvoller?
Und noch die Anmerkung dazu, das finde ich, macht es noch unabhängiger von der eigentlich eingesetzten Sprache, weil es dann halt vollkommen egal ist, ob der Service in JavaScript geschrieben ist oder in Go oder in Java.
Genau.
Genau.
Also, ja, das sieht man tatsächlich sehr häufig, dass ein Projekt über verschiedene Repositories verteilt ist, eine Architektur über verschiedene Microservices.
Und ich denke, es macht durchaus Sinn, das ist ja einer der Vorteile von dem Docs-as-Code-Ansatz, dass man die Dokumentation beim Code-Liegen hat, dass man eben zum Beispiel auch Code referenzieren kann, dass man den inkludieren kann und der dann in der Dokumentation weiterlebt mit jedem Bauen der Dokumentation.
Und gerade weil docToolchain eben ein Config-File und ein Wrapper ist, kann ich diesen Wrapper in jedes dieser Repositories legen, um diese Repositories einzeln zu rendern.
Aber ich kann eben auch ein übergeordnetes Architektur-Repository aufmachen, in dem ich dann alles zusammenziehe.
Und ich mache das ganz gerne mit einem einfachen Git-Clone der TV1, dass ich eben ein kleines Skript habe, wo ich die anderen Repositories reinziehe und dann aus der Hauptdokumentation referenzieren kann.
Das funktioniert super und ich habe ehrlich gesagt noch kein Entwicklungs-Environment erlebt, wo kein Git-Client installiert war, sodass dieser Ansatz super funktioniert.
Antora ist ja auch nochmal so ein Static-Site-Generator, der coole Features hat.
Antora nennt immer das als große Feature, dass die Dokumentation in verteilten Repositories liegen kann, weil eben da ein JavaScript-basierter Git-Client mit dabei ist.
Aber ich habe diesen Use-Case eben noch nicht gefunden, da ich eben extra ein Git-Client brauche.
Aber da sagst du gerade noch was mit dem Static-Site-Generator.
Also wir sind vorhin schon ziemlich oft auf dieses Generieren nach Confluence gegangen.
Ich glaube auch, das ist das, was ich irgendwie am häufigsten in der Praxis erlebt habe.
Ich habe jetzt eine Frage.
Kann man, du hast mal einen Vortrag gehalten, damals, ich weiß nicht, das ist ein oder zwei Jahre her, über Microsites für Architektur-Dokumentation.
Und meine Frage, kann man mit der Doc-Tool-Chain auch Microsites generieren oder ist das noch nicht möglich?
Doch, also das ist jetzt eigentlich mit einer der Haupt-Use-Case, die ich benutze.
Ich kann tatsächlich, es sind glaube ich vier Befehle, ich habe mal einen Tweet verfasst, wo sie drin sind, da ich mit einem Curl den Doc-Tool-Chain-Wrapper ziehe, den executable mache.
Dann führe ich den Befehl Download Template aus, mit dem ich dann das Arc42-Template mir ziehe, die aktuellste Version.
Er fragt dann nur noch, welche Sprache und mit oder ohne Hilfe.
Und mit dem Befehl Generate Site baue ich dann tatsächlich eine Microsite auf mit Landing-Page, mit der Dokumentation.
Es ist sogar eine lokale Suche mit dabei über Luna.js und da wird JBake als Static-Site-Generator genutzt.
Und JBake kann eben Asciidoc und Markdown und HTML und über das HTML-Feature wird dann eben auch Restructured-Text zum Beispiel reingezogen, dass man das nochmal extern aufruft und nach HTML konvertiert.
Somit ist das eines der großen Features, aber es sind eben auch so Features dabei, dass ich dann eben auch PDF rauslassen kann, dass ich es nach Konfluence noch exportieren kann.
Da ich aber zum Beispiel auch, wenn ich komplexere Tabellen habe und um mal wieder auf das Thema Diagramme zurückzukommen, unterstütze ich auch ganz gern so ein Diagramm mit einer Tabelle, wo ich die Elemente noch näher beschreibe.
Und Doc-Tool-Chain kann zum Beispiel Excel-Files einlesen, nach Asciidoc konvertieren und der nimmt total viele Features von dem Excel-File mit.
Die Spaltenbreite, Pulse-Bands, Row-Bands, Hintergrundfarben, Vertical- Horizontal-Alignment, sodass ich da viele Möglichkeiten habe, mich in Excel auszutoben, das dann aber in die Dokumentation reinzuziehen.
Und da haben wir dann auch wieder den interessanten Excel-File wie mit den Image-Diffs, dass dadurch, dass ich das in eine Textform rausgezogen habe, kann ich dann von dem Excel-File tatsächlich den Diff sehen und sehen, was sich geändert hat.
Aber nur nicht indirekt.
Also ich würde das Excel-File pflegen und die Pipeline würde dann die Informationen aus dem Excel-File in die Tool-Chain pusten und in der Transformation von der Tool-Chain würde ich dann das Diff sehen.
Genau.
Und das ist dann so ein Punkt, wo man eigentlich als Entwickler sagt, ja, das Export, also aus Excel exportierte Tabelle, das ist dann eigentlich generiert und sollte eigentlich nur im Build-Folder leben.
Das Ganze kam aber als Pull-Request, ich weiß jetzt gar nicht mehr von wem rein, müssten wir nochmal raussuchen, und derjenige hat das Ganze eben in den Source-Folder reingelegt, da wo es eben versioniert wird.
Und wir hatten dann eine kurze Diskussion, ja, sollte es nicht eigentlich im Build-Folder liegen?
Er hat gesagt, nein, weil die Versionierung bringt eben den Vorteil, dass ich einen Diff machen kann und dass ich eben sehe, dass sich da was geändert hat.
Und das ist so, ja, da muss man ein bisschen über den eigenen Schatten springen, dass man wahrscheinlich das Excel-File und das exportierte ASCII-Doc versioniert, aber es ist hilfreich.
Genau, du hast schon gesagt, wir müssen mal wieder zurück zu Diagrammen kommen, das stimmt, aber jetzt hat man schon mal dich hier, denn es ist klar, dass man sich gerne Fragen zu docToolchain stellt.
Genau, ich glaube, rausgehört zu haben, dass du lieber PlantUML machst als Draw.io, stimmt das?
Nein, also mittlerweile, PlantUML ist toll für Sequence-Diagramme, weil da gibt es keine Layout-Probleme.
Bei allem anderen, wie hier schon gesagt worden, ist 7 plus minus 2, das ist prima.
Wenn ich Gefahr laufe, dass es komplexer wird, dann sollte ich aufpassen.
Aber das 7 plus minus 2, das ist tatsächlich ein guter Ansatz, um übersichtliche Diagramme zu erstellen.
Also über die Zeit habe ich so ein paar Prinzipien mir angewöhnt, dass zum Beispiel ein Diagramm, ohne rein zu zoomen, auf einer Bildschirmseite lesbar sein sollte.
Früher habe ich gesagt, auf einer DIN A4-Seite, mittlerweile drucke ich nichts mehr, deswegen sage ich Bildschirmseite und ich meine nicht diese riesigen 8K-Monitore, sondern ich meine einen normalen Notebook-Bildschirm ohne zoomen und das bedeutet eigentlich schon, ich kann gar nicht so viele Elemente draufsetzen, sondern ich muss auf einer gewissen Abstraktionsebene bleiben, bei einer gewissen Flughöhe und da hilft von Simon Brown der C4-Ansatz, dass ich auf der obersten Ebene nur den Kontext darstelle, nächste Ebene gehe ich in die einzelnen Container rein, dann Components, die Classes, das ist meistens für eine Architektur zu dynamisch, dass ich das dann nicht mehr darstelle, aber das hilft eben die Abstraktionsebene beizubehalten und dann eben wenig Elemente in einem Diagramm zu haben.
Das Diagramms.net hat noch ein paar andere nette Vorteile, nicht nur für Architekturdiagramme, zum Beispiel auch, wenn ich ein Usermanual mache und mit Screenshots arbeite und irgendwas highlighten will oder so.
Das ist auch so ein Mindset, dass man mit einem Diagramm-Tool mit Screenshots arbeitet, aber ich habe herausgefunden, das ist ganz nützlich, weil wenn ich den Screenshot reinsetze und dann mit Pfeilen oder Highlights arbeite oder so, dann habe ich im Source diese Pfeile und Highlights getrennt vom Screenshot und wenn ich das Ganze dann irgendwann mal aktualisieren muss, ein neuer Screenshot rein, dann hänge ich einfach den Screenshot rein und gucke, ob die Pfeile noch passen.
Das sind einfach Features, die sind toll dabei.
Ich muss zugeben, ich habe in der Architekturdokumentation noch nicht sehr oft Screenshots gesehen.
Genau, deswegen, das ist dann eher so ein Usermanual oder so, aber auch das hat man teilweise mitzuarbeiten.
Denkst du, es würde Sinn machen, mehr Screenshots in Architekturdokumentation zu packen?
Ich glaube, es kommt auf die Architektur drauf an.
Wenn man irgendwie mit einer Architektur anfängt, eine zu verbessern und irgendwie auf Probleme in der alten hinweisen möchte, vielleicht ist dann ein Screenshot passend.
Genau, du hast schon ganz oft gesagt, Sequenzdiagramme und meine Frage wäre, was die Diagrammtypen sind, die du am häufigsten in Architekturdokumentationen einsetzt?
Ja, eigentlich Boxes und Lines.
Also gar nicht so an den UML-Diagrammen entlanghangeln, sondern das, was passt.
Wir waren vorhin beim Enterprise Architect und das ist ein Feature, was ich an ihm liebe, dass man Elemente aus verschiedenen Diagrammtypen zusammenschmeißen kann.
Dass ich eben auch an einem Klassendiagramm mal einen Actor dranhängen kann, damit ich weiß, der und der Entwickler kümmert sich um die und die Klasse.
Und von daher, ich meine, das arc42 Template, das bringt ja schon einige Vorschläge für bestimmte Diagrammtypen zusammen und das sind dann eigentlich auch so die groben Diagrammtypen, die ich immer benutze.
Wichtig für mich ist halt vor allem auch, und wir hatten ja jetzt das Ganze hier als mehr als nur Linien und Kästchen genannt, es kommt nicht nur auf den Diagrammtyp drauf an, ob etwas lesbar ist, sondern eben auch, wie ich das Ganze aufbaue.
Und ich glaube, es hat jeder schon diese Diagramme gesehen, wo sehr viel White Space drin ist, wo zwischen den Blöcken ganz lange Linien sind, die ich irgendwie visuell verfolgen muss.
Dann kleine Schriften in den Blöcken drin, sodass, wenn ich das ganze Diagramm, was zwar nur wenig Elemente hat, aber wenn ich es eben in der Zoomstufe habe, dass ich es eben komplett übersehen kann, dass dann eben die Schriften teilweise zu klein sind, da ich die nicht mehr lesen kann.
Das ist zum Beispiel auch so ein Ding, wo ich sage, da kann man ein Diagramm viel verbessern, dass man eben White Space rausnimmt, dass man die Sachen enger zusammensetzt, dass man auch auf das Optische achtet.
Ich mache es zum Beispiel ganz gerne, dass ich die Schriftgröße von den Blöcken größer, teilweise fett mache, damit man das auf jeden Fall einfach lesen kann und zur Beschriftung von Pfeilen kleiner mache, weil man muss erst mal mit dem ersten Blick die Blöcke erfassen und dann geht man die Pfeile entlang und dann hilft da die Beschriftung, was macht eigentlich dieser Pfeil und dieses Visuelle.
Das finde ich total wichtig.
Da gibt es auch ein Talk, eine Aufzeichnung vom Jochem Schulenklopper und der geht genau auf diese Sachen, auf das Visuelle sehr stark ein und der hat zum Beispiel auch diesen Punkt angebracht, was ist mit den Farben und Farben haben bei uns eigentlich so eine intuitive Bedeutung, dass zum Beispiel Rot, Achtung, da ist irgendwas komisch, aber wir setzen es in Diagrammen nicht so ein.
Wenn ich zum Beispiel an AWS-Diagramme denke, ich glaube der S3-Bucket, ist Rot.
Warum ist der eigentlich Rot?
Sollte ich den meiden?
Und wenn man auf sowas achtet, dass man die Farben auch richtig einsetzt, Gold wert, also Grün ist etwas, damit sind wir zufrieden, Blau ist eh stabil, Orange und Rot, nee, also da sollten wir dran arbeiten.
Das bringt was.
Auch hatte ich mal ein Projekt, wo ich die Kästen so groß gemacht habe, wie halt die Beschriftung war.
Also wenn die Beschriftung der Name etwas größer war, dann brauchte ich ein bisschen mehr Platz.
Habe da also einen größeren Kasten genommen und wurde dann sofort gefragt, warum ist jetzt dieser Kasten größer als jener?
Und war mir erst gar nicht so bewusst, dass Leute darauf achten, aber auch das kann eben eine Bedeutung haben.
Kann zum Beispiel Komplexität sein oder sowas.
Und auf diese visuelle Sprache zu achten und sie auch zu erklären, dass man eine Legende in sein Diagramm reinbringt und in der Legende kann man zum Beispiel auch die Quelle des Diagramms gleich nennen und den Autor, dass man einen Ansprechpartner hat, dass man die Quelle auch findet, dass man was verändern kann, ist eben auch ganz wichtig.
Und ich denke, das sollte man nur weglassen, wenn man eine visuelle Sprache benutzt, die auch irgendwo anders definiert ist.
Aber selbst dann sollte man auf diese Definitionen verweisen, dass man sagen kann, hey, wir benutzen hier den, keine Ahnung, AWS-Diagramm-Style und hier findet ihr den.
Das sind alle S3-Bucktes rot.
Ja, genau.
Aber dann würdest du auch in dieser Legendentabelle, würdest du auch beschreiben, wenn etwas rot ist, dann bedeutet das Legacy-System wird abgelöst, läuft noch bis Ende 23 oder so, und wenn etwas grün ist, wurde vor zwei Jahren abgelöst oder sowas.
Also du würdest das schon nicht nur die verwendeten Typen von Dingen, also Kasten, Pfeil, was wir da nicht alles haben, sondern auch wirklich die Farben reinschreiben und in deinem Beispiel vorhin hätte die Größe eines Kästchens eine Bedeutung gehabt, hättest du möglicherweise auch noch als Anmerkung bei dem Kasten, wenn größer, dann wichtiger oder wenn größer, dann umfangreicher oder so da reingeschrieben.
Genau und da ist es halt wichtig, dass man eben auch damit arbeitet, was intuitiv Sinn macht.
Also es gibt ja diese Spielereien, wo man so ein paar Farbnamen hat und grün in blau schreibt und solche Geschichten und das verwirrt ja.
Es würde genauso verwirren, wenn ich jetzt definieren würde, ein kleines Kästchen hat große Komplexität, großes Kästchen hat kleine Komplexität oder sowas.
Und deswegen…