Mehr als Pfeile und Kästen: Architekturdiagramme mit Ralf D. Müller und Lisa Moritz
Summary
TLDRIn this engaging discussion, Ralf Müller, a Chief Architect at DB Systel, shares his insights on software architecture documentation. Ralf emphasizes the importance of clear and maintainable architectural diagrams, highlighting his journey from traditional documentation methods to adopting the DocToolchain approach. He discusses the challenges of keeping diagrams up-to-date and how scripting and tools like PlantUML and diagrams.net have streamlined the process. Ralf also explores the role of visual language in diagrams, advocating for intuitive design and the use of legends to enhance understanding. The conversation touches on the benefits of open-source collaboration and the potential for cross-project use of diagrams, emphasizing the value of collective knowledge and continuous improvement.
Takeaways
- 🌟 The importance of clear and effective communication in software architecture documentation was emphasized, highlighting the role of diagrams and visual representations.
- 📈 Ralf Müller, as a Chief Architect, stressed the significance of architecture documentation and his journey towards improving it through scripting and automation.
- 🔄 The evolution from traditional text-based documentation to incorporating tools like draw.io, diagrams.net, and the challenges of keeping diagrams up-to-date were discussed.
- 🔧 The transition to using code (doctools Code approach) for generating documentation was explored, including the benefits of automating the process and integrating UML tools.
- 📚 The impact of using Markdown and AsciiDoctor for creating and maintaining documentation was highlighted, offering a more dynamic and flexible approach.
- 🔗 The discussion touched on the integration of diagrams within documentation, ensuring that they are referenced and can be easily updated as the system evolves.
- 🎨 The role of visual language in diagrams, including the use of colors, shapes, and sizes, was emphasized to convey meaning and structure within architectural documentation.
- 👥 The value of collaboration and feedback in refining documentation practices was underscored, with the mention of open-source contributions and community involvement.
- 🛠️ The practical aspects of handling diagram sources and version control were discussed, stressing the need for organized management to facilitate easy updates and revisions.
- 📊 The potential of using tools like PlantUML for creating diagrams that are both aesthetically pleasing and semantically meaningful was presented, with tips on maintaining clarity and simplicity.
- 🚀 The conversation concluded with a look towards future improvements and the continuous development of the doctools Code approach, aiming to enhance the creation and maintenance of architecture documentation.
Q & A
What is Ralf Müller's profession and main area of focus?
-Ralf Müller is a Chief Architect at the DB Systel, the IT partner of the railway company. His main focus is on architecture documentation.
How did Ralf Müller become interested in architecture documentation?
-Ralf Müller became interested in architecture documentation after years of working as a developer. He wanted to understand the bigger picture and realized that architecture involves a lot of communication and documentation.
What challenges did Ralf face with traditional text processing and UML tools?
-Ralf found that while traditional text processing allowed for a quick initial draft, keeping it up-to-date was difficult. As for UML tools, he found it cumbersome to manually update diagrams across all documentation whenever there was a change.
How did Ralf Müller improve his documentation process?
-Ralf improved his documentation process by using scripts to automate the extraction of diagrams from his UML tool and embedding them into his documentation. This led him to the doccscript approach, which made the process easier and allowed for diagrams to be automatically updated in his documentation.
What is the doccscript approach and how does it benefit architecture documentation?
-The doccscript approach is a method of architecture documentation that involves using scripts to automate the generation and maintenance of diagrams and other documentation. It benefits architecture documentation by making the process of keeping diagrams and documentation up-to-date more efficient and less error-prone.
What was the first script Ralf Müller created for his documentation?
-The first script Ralf Müller created was for automatically exporting diagrams from Enterprise Architect, a tool he was using for architecture modeling, and then using the doccscript approach to update his documentation with the exported images.
How did Ralf Müller's scripts evolve into the doccscript project?
-Ralf Müller's scripts evolved into the doccscript project when he decided to make them open source. He wanted others to be able to use and improve upon his scripts. Over time, many contributors enhanced the project, adding new features and use cases, which led to doccscript becoming a larger project with a variety of modules.
What is the significance of the doccscript project for architecture documentation?
-The doccscript project is significant because it provides a set of tools and scripts for automating the creation and maintenance of architecture documentation. It allows for easier integration of diagrams and other visual elements, and it supports a variety of markup languages, making it a versatile tool for architects and developers.
What are some of the benefits of using a tool like draw.io or diagrams.net for architecture diagrams?
-Tools like draw.io or diagrams.net are popular because they offer a what-you-see-is-what-you-get (WYSIWYG) interface for creating diagrams. They are intuitive and widely used, making it easier for team members to collaborate and maintain documentation.
How does Ralf Müller handle feedback and improvements for the doccscript project?
-Ralf Müller handles feedback and improvements by engaging with the community and collaborators. He is open to suggestions and takes user feedback into account when updating the doccscript project. This collaborative approach has allowed the project to grow and improve over time.
Outlines
🤝 Introduction and Guest
The paragraph introduces Ralf Müller as a guest in a new episode of Software Architecture. Ralf is a Chief Architect at DB Systel, focusing on architecture documentation. The conversation revolves around the challenges and evolution of documenting architectural diagrams and the motivation behind Ralf's interest in improving documentation practices.
📈 Evolution of Documentation Tools
Ralf discusses his journey from using basic text processing to more sophisticated tools for architecture documentation. He talks about the limitations of traditional methods like Wikis and the transition to tools like Enterprise Architect. He also shares his experience with creating scripts to automate the process of extracting diagrams and embedding them into documentation.
🔄 Feedback and Improvement
The conversation touches on the importance of feedback in the development of documentation tools. Ralf shares how his scripts evolved into a project called 'doctoolchain', which became open-source and contributed to by various contractors. The paragraph highlights the collaborative effort in refining tools and the impact of community involvement on the project's growth.
📊 Handling Diagrams in Documentation
Ralf discusses the challenges of managing diagrams in documentation, such as keeping them up-to-date and the difficulties with different file formats. He talks about his experiences with tools like draw.io and diagrams.net, and the benefits of using a 'what you see is what you get' editor. The paragraph also touches on the importance of version control for diagrams.
🌐 Accessibility and Styling in Diagrams
The paragraph delves into the accessibility of diagrams, emphasizing the importance of styling for visually impaired users. Ralf shares insights on the benefits of using PlantUML and the potential for creating diagrams that can be understood by both sighted and blind users. The conversation also covers the significance of maintaining a clear and concise visual language in diagrams.
🔧 Customization and Integration
Ralf talks about the customization options available in doctoolchain, including support for different markup languages and the integration of mermaid diagrams. The paragraph discusses the flexibility of the toolchain and its potential for use in various technology ecosystems, not just Java. The conversation also highlights the ease of setting up a public diagram server for various diagram types.
📚 Structuring Documentation
The paragraph focuses on strategies for structuring and maintaining architectural documentation. Ralf discusses the use of doctoolchain for managing multiple report stories and the benefits of keeping documentation close to the code. He also talks about the ability to generate microsites for architecture documentation and the features of static site generators.
🎨 Aesthetics and Clarity in Diagrams
Ralf emphasizes the importance of aesthetics and clarity in diagrams, discussing principles such as the use of white space and the need for diagrams to be readable without zooming. He shares his approach to creating diagrams that are concise and easy to understand, including the use of visual cues and the avoidance of overly complex diagrams.
🌈 Use of Colors and Visual Language
The conversation turns to the strategic use of colors and the development of a visual language within diagrams. Ralf discusses the intuitive meanings of colors and the importance of defining and explaining this language within a diagram's legend. He also talks about the impact of diagram aesthetics on understanding and the need for a sanity check when creating diagrams.
🔄 Sharing and Collaborating on Diagrams
Ralf talks about the benefits of sharing diagrams and the collaborative potential within teams. He discusses the impact of having the creator's name on diagrams and the reduction of the 'bus factor' when multiple team members are involved in documentation. The paragraph also touches on the practice of acknowledging contributors in documentation and the potential for open-source approaches.
Mindmap
Keywords
💡Software Architecture
💡Architecture Documentation
💡docToolchain
💡UML Tools
💡Enterprise Architecture
💡PlantUML
💡Version Control
💡Visual Communication
💡Open Source
💡Architecture Diagrams
💡Collaboration
Highlights
Ralf Müller, Chief Architect at DB Systel, discusses his passion for architecture documentation and how he transitioned from being a developer to focusing on architectural aspects.
Ralf emphasizes the importance of communication and documentation in architecture, and how he began to explore ways to improve the documentation process using scripts and tools.
The conversation delves into the challenges of keeping documentation up-to-date, especially when it comes to diagrams, and how Ralf started using scripts to automate the process of extracting diagrams from UML tools.
Ralf shares his journey towards creating the doccscript approach, which simplifies the process of embedding diagrams and keeping documentation current.
The discussion highlights the evolution of Ralf's scripts into the doccscript language, which has since become an open-source project with contributions from various contractors, improving and expanding its capabilities.
Ralf talks about the benefits of using doccscript, including the ability to easily update diagrams and documentation without needing access to expensive tools like Enterprise Architect.
The conversation touches on the topic of intuitive diagram editors like draw.io (now diagrams.net) and how they can be integrated with the doccscript approach for a more streamlined documentation experience.
Ralf addresses the issue of version control for diagrams, emphasizing the importance of being able to trace changes and updates in architecture documentation.
The discussion explores the advantages of using PlantUML, particularly for sequence diagrams, and how it can enhance collaboration within teams by allowing members to easily compare and contrast different versions of diagrams.
Ralf shares insights on the importance of accessibility in architecture documentation, highlighting how the doccscript approach can make diagrams more accessible to users with disabilities.
The conversation highlights the versatility of the doccscript approach, which is not limited to Java ecosystems but can be applied to various technologies and projects.
Ralf discusses the potential of using the doccscript approach to generate microsites for architecture documentation, emphasizing its flexibility and the ability to create tailored documentation for different audiences.
The discussion concludes with Ralf sharing his excitement for the upcoming JavaLand conference, where he will be presenting on the topic of diagrams and architecture documentation, offering attendees a chance to learn and engage with these concepts.
Transcripts
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
basierter auf einer ich sage mal
hitzigen Diskussion als damals mit mir
über Youtube Dokumentation gesprochen
hatte und da dachten wir wie ergreifen
die Chance schnappen uns Ralf und
sprechen mal mit ihm über
architekturdiagramme und über
Architektur Dokumentation genau und wir
freuen uns auf jeden Fall riesig wenn
ihr auch Fragen stellt und vielleicht
auch Kommentare liefert das kam schon
ein paar Sachen im Vorfeld aber genau
das ja so viel zu Einleitung jetzt
geht's 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 dbsstelle dem
IT-Partner der Bahn eingestellt und
kümmere mich darum alle möglichen
Probleme aber vor allem mein
Steckenpferd Architektur Dokumentation
wie bist Du daran gekommen 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 Range
gewagt an die Definition was ist
eigentlich Architektur habe gemerkt dass
Architektur eben viel kommunizieren und
dokumentieren ist und kommunizieren über
die Dokumentation und habe dann gemerkt
dass so das Dokumentieren mit
Textverarbeitung und Co nicht so
wirklich Spaß macht weil man kriegt zwar
einen schnellen ersten Wurf hin aber
dann das aktuell zu halten ist dann doch
etwas schwieriger und habe dann
angefangen ja mich damit zu beschäftigen
wie kann ich es besser machen wie kann
ich mit Skripten zum Beispiel aus meinem
UML Tool die Diagramme rausziehen und
automatisch in meine Dokumentation
einbetten und so bin ich dann zu dem
docess Code Ansatz gekommen und ark42
und seitdem baue ich das immer weiter
aus das ist immer leichter wird eben
dieses gespannt so nutzen was waren die
ersten Tools mit denen du dokumentiert
hast also bevor du zu dem doktor-ansatz
kamst ja das ist also was man halt so
kennt die normale Textbearbeitung was
natürlich dann immer irgendwie so zu so
einem
orientierten
orientierten Dokumentation führt ja wo
man dann immer auch die Probleme hat und
irgendwelchen verweisen und wenn man
dann auf einen 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 es auch damals schon und
waren als 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 Sachen Diagramm immer
so ein bisschen
schwierig ist die wie gehe ich damit
Diagramm um erstelle ich die in einem
externen Tool lad die dann hoch und wenn
es dann hochgeladen habe genauso wie bei
einer Textverarbeitung wenn ich da
irgendwie was per Copy and pace
reingespielt habe wenn sich dann das
Diagramm irgendwie ändert dann muss ich
mich wieder daran erinnern wo habe ich
es überall per Copy and Paste
reingebracht wo muss ich es
aktualisieren und das wird dann mit der
Zeit ziemlich aufwendig und das führt
dann eigentlich meistens dazu dass man
eben leider doch nicht aktualisiert
aber ich muss gerade so an den
Enterprise Architekt denken oder nur
eine Handvoll ausgewählter Personen
Zugang zu diesem sauten Schule hat was
kaum einer bedienen kann und die sind
dann alle im Urlaub und dann wird dieser
Architektur Dokumentation einfach nicht
angepasst weil kann halt dann keine
ja ja da spricht so aber ein sehr
schönes Thema an also der Enterprise
Architekt der geht ja noch vom von den
Lizenzkosten her also dass das ist ja
was wo man tatsächlich eben Zugriff
geben kann aber
die Bedienung ist nicht so ganz einfach
anruhr im l-tools sind ja tatsächlich so
teuer dass ja nur wenig Leute in der
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 benennst im
Modell um und dann ist die erste Frage
in wie viel sichten hat sich das jetzt
geändert
welche Diagramme welche sichten werden
in Dokumenten verwendet und wie kann ich
das jetzt aktuellisieren und zwar in der
Tat so der erste das erste Skript in
meiner skriptsammlung die dann zu Doktor
wurde
da ich eben gesagt habe irgendwie muss
ich diese Diagramme automatisiert
rausbekommen und habe es dann geschafft
in Enterprise Architekt headless zu
starten in einem Skript alle Diagramme
zu exportieren
und mich dann den doxos Code Ansatz
verwendet dann habe ich ja mein Mark
down oder besser noch aski dog was diese
images referenziert aus einem Folder das
heißt sobald ich die Images neu
exportiert habe und dann die
Dokumentation Bau dann habe ich die eben
auch in meiner Dokumentation
aktualisiert
und das ist so schon ganz 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
Diagramm auf aktuellen Stand was gerade
schon gesagt die Doktor chain das war
eine der ersten Sachen mit dem
Enterprise Architekt ich frage mich
gerade ob das so war dass du so deine
Scriptsammlung irgendwo rumliegen
hattest und irgendwann hast du gemerkt
ach das ist eigentlich so cool ich
möchte das Teilen und dann ist so daraus
die Doktor geworden oder ist das
irgendwie anders gekommen ja es war
damals ich mein Soundprojekt der
ziemlich cool ne also seine eigene Vater
und deswegen habe ich mir eben auch
gedacht dieses Skripte die ich habe
warum nicht Open Source machen ähm
und damit auch die Chance haben das
andere drüber gucken und sie verbessern
und die Rechnung ist aufgegangen also
mittlerweile haben wir da relativ viele
Kontraktoren die eben tatsächlich das
ganze verbessert haben die immer mal
wieder irgendwelche anderen Use Cases
haben und damit ja zu dem großen Ganzen
beigetragen haben dadurch ist die
Doktoren eigentlich ein relativ großes
Projekt geworden und dem man aber
meistens eben nur einen Ausschnitt sieht
also gerade der static side Generator
oder der Export nach conference ist sehr
beliebt und andere Module werden dann
nicht ganz so tief betrachtet
und wir sind ja jetzt beim Diagrammen da
ist ja
Diagramme im doxos Code Ansatz
planturmeln und sowas ist ja immer nicht
ganz so einfach zu händeln
und
es gibt ja dieses Tool früher hier ist
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 das ich
mich da unterhalten habe hey es gibt für
Visual Studio Code da ein entsprechendes
Plugin mit alexander Schwarz hatte ja
auch das Astrid Doktor Plugin für
Intelli J und da habe ich mir gedacht
Mensch der hat doch sicher das Know-how
wie man da eben entsprechend
Plugin für intelligenz macht
und in dem Zuge dieses Open Source
austauschst
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
intelligen gemacht und ja das ist jetzt
für intelligente das direcross.net
Plugin was jetzt eben auch im Doktor
change Namespace liegt
lange Herleitung aber das war jetzt so
manchmal
loswerden wollte dass eben
das Doktor Jane vieles umfasst viele
Ansätze und das gerade dieses Plugin
eben jetzt sehr gut hilft
Diagramme besser zum
damit hast du aus Versehen auf eine
Frage beantwortet 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
das what you Sears what you get Editoren
wie Gira conference Visio intuitiver
sind und man mit drolshain eine unnötige
Hürde schafft also du hast eben einmal
gesagt dass du ja von Dr Jane nach
conference die point quasi kannst
oder veröffentlichen die vielleicht auch
zu viel gesagt und du hast auch gesagt
dass man diese draw iO oder nett oder
die what is what you get Diagramm
Editoren mit der Doktor chain nutzen
kann
denkst du denn dass das Argument häufig
kommt dass dort intuitiv ist und dass
man lieber nur in Konferenz und so
weiter arbeiten sollte
ja also diese Argument kommt immer
wieder und es kommt immer darauf an wer
mit der Dokumentation arbeitet wer sie
erstellen möchte
ich erlebe es bei Techis immer wieder
dass sie den Docs Code Ansatz lieben sie
sind den ganzen Tag in ihrer Idee
möchten die am liebsten gar nicht
verlassen und wenn sie dann die
Dokumentation auch in die 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 eigentlich von Markdown
ich schreibe so eine Dokumentation
runter wie eine E-Mail und
dann merke ich okay Überschriften
formatieren ja ein Hashtag davor dass
das einfach das geht auch in asketok und
den as geht doch kann ich dann genauso
wie ich in Wikis besondere Formatierung
ausfindig machen kann und so kann ich
das dann auch in afdok und dann ist
eigentlich die größere Hürde
geht dass man wenn man da irgendwie äh
request hat da irgendwelche
Probleme hat dass man die überwindet
aber das ist halt 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 eins
bekommen haben gesagt haben oh das ist
aber komplex und nee das ist
unpraktikabel ja und ich denke mit git
haben wir Techies ein ja
Dokumentenmanagementsystem was perfekt
ist was eben die minimale Komplexität
mitbringt die man braucht
ja und mit den Diagrammen
also gerade mit dem direcrimes.net ist
deshalb 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 reposttory
und kann das direkt wieder editierbar
öffnen
und das ist auf so vielen Ebenen super
klasse weil was mich an vielen
Diagrammen stört ist wenn man so ein
Projekt reinkommt und fragte ob mir die
Architektur ja hier guck mal ich habe
hier
PDF das von von der 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 es halt
schon ziemlich ärgerlich wenn man dann
das ganze Modell irgendwie neu aufsetzen
muss
und deshalb bei dem direcrimes.net wenn
ich das repostory kennen wenn ich das
PNG File habe dann kann ich direkt damit
arbeiten bei plantronell ist es ähnlich
und da fällt mir auch gerade so ein
Punkt ein bezüglich Plan du ml viele
Leute sagen ihr plant URL ist ist das
sieht so hässlich aus aber ich sag das
ist ein Vorteil das ist ein Vorteil wenn
ich an dem Design erkenne welches Tool
das war weil ich dann schon weiß wo ich
suchen muss
und da finde ich eben leichter auch die
source
es gibt auf jeden Fall ich hätte eine
Nachfrage noch mal du sagst ihm also
genau ich kenne den Plan und ich kenne
auch was ich mich frage bei planto ml
sich ja in der geht Historie ganz klar
wo sich was geändert hat weil das ja das
ist einfach textbasierte Ansatz um die
Diagramme zu beschreiben
habe ich dieselben Möglichkeiten auch
wenn ich es BG oder einen PNG Einchecken
dass ich wirklich die das Gif visuell
sehe und sehe was hat sich geändert oder
habe ich die Chance dann vertan wenn ich
pro einsetze
ist eine sehr gute Frage
ja das ist ein großer Vorteil von plant
URL und
das ist halt bei bei
grounds.net oder troyo nicht so
es gibt aber sehr gute
grafische Diff Tools für
images
wenn man nicht zu viel an dem Diagramm
ändert dann sieht man über so ein Diff
eben auch optisch was ich geändert hat
ja
meistens ist es dann doch so also
es ist selten dass ich mal irgendwie den
dift bei einem Diagramm einsetze wobei
bei plant UML liebe ich wenn man mit
Sequenz Diagrammen arbeitet und im Team
irgendwie so verschiedene Vorschläge
vergleichen möchte und dann jedes Team
Mitglied sich sonst Sequenzdiagramm
einfach nehmen kann bisschen verändern
kann und man sieht genau was was ist da
anders an welcher Stelle hat derjenige
gearbeitet und für die Zusammenarbeit
ist das Gold wert
6% gerade so ein paar Anmerkungen und
Fragen über die Chats rein und ich würde
dir gerne erst die die ich glaube plant
UML Anmerkungen Vorlesen was man
Anmerkungen sind Jendrik Oltmann sagt
plant UL kann man auch stylen dann sieht
sogar schick aus
und ach ja diese die Namen aussprechen
ist immer das größte Highlight hier Abo
mormos sagt ich denke wenn man die
Standard 7 plus minus zwei
komponentenregel einhält werden planto
Diagramme auch nicht so unübersichtlich
ich glaube da hat er auch recht und ich
glaube dann sind sie auch noch bartbarer
als wenn man zu viel versucht dann ein
Diagramms hatten
definitiv also gerade ist 7 plus minus 2
ist bei plant ganz wichtig weil
ansonsten wird das Ganze schwer
erwartbar die Sache mit dem Styling das
ja kann man machen
da habe ich aber oftmals das Problem
dass das plant Ulm liagramm dann mehr
Styling Optionen 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
dass das wird einem gar nicht so bewusst
aber
ich habe einen blinden Kollegen der auf
mich zukam und gesagt hat er hat plant
Urmel 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 plant oder plant OML
Diagramme erstellen dass die
accessibility höher ist weil man eben
das 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 in include ist dann macht das diesen
Use Case wieder kaputt
man musste gerade noch dran denken ich
habe auch gelernt dass die Tabellen in
Konferenz sind auch nicht exzessibel für
Blinde Nutzer ist noch etwas was wir vor
einiger Zeit zugetragen wurde also da
kommen immer noch mehr zu und ich glaube
die also noch mehr Dinge um drauf und
ich glaube gerade dieser magdon oder
aski Bock Ansatz und dann eben plant ist
ja quasi maximal Exzesse will was ja
das maximale Wirkung genau 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
Architekt headless gestartet und ihn
interessiert hat sich Sparks mal den
Ansatz Enterprise Architekt auf diese
Weise zu nutzen geäußert
wie soll ich darauf antworten
genau kommt drauf an ist die Antwort
eines Architekten also nein ich habe da
nichts mitbekommen
es ist es ich glaube die
Dokumentations Engine im Enterprise
Architekt ist mittlerweile besser
geworden damals ja wurde so eine html
exportiert mit dem man nur schwer was
anfangen konnte
aber nein da habe ich kein kein weiteres
Feedback bekommen apropos damals seit
wann gibt es die Doktor Training
eigentlich
oder müsste ich jetzt Lügen ich weiß
nicht muss man mal gucken welches der
älteste commit ist
aber es sind ja Jahre es sind einige
Jahre wenn euch kam ich hatte es noch
rausgefunden in einer Projektliste dass
ich irgendwann 2017 mal damit rumspielen
durfte also es ist auf jeden Fall schon
ein bisschen
genau es gibt noch zwei Fragen zu eben
dieser Doktor chain einmal gibt es
Maximilian Schmidt fragt auf Youtube
gibt es in der Doktor chain auch eine
Integration für mermaid
das Interessante ist also mittlerweile
unterstützt die doctool chain nicht nur
huskydog sondern auch
Markdown und restructured Text und über
Plugins kann man theoretisch noch
weitere Mark Absprachen reinnehmen und
dann hängt es an der Mark Absprache was
die unterstützt und aski dog 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
und solche Geschichten
und der Kroki Server der nimmt einem das
ganze ab und es geht Doktor hat Support
für den cookies-server da ich einfach
über zwei Attribute den konfiguriere es
gibt ein Public Cookie Server den ich
natürlich für Projekte nicht einsetzen
würde aber
der ist relativ relativ leicht selbst
aufgesetzt und darüber werden alle
möglichen Diagrammtypen unterstützt und
eben auch mermaid
sehr gut Thomas Schwert hatte noch die
Anmerkung das Bit bucket einen
grandioses diphon-bnb PNGs eingebaut hat
auf wirklich gute Weise also das scheint
sich zu lohnen dass man anzuschauen wenn
man muss und es kam noch die Frage von
Hans Fallada 42 auf Twitch sieht sehr
nice aus ist die doktool chain eher für
das Java Ökosystem gedacht oder kann ich
auch engular und notapplikationen
Web-Apps damit versorgen
also seit Anfang des Jahres haben wir
mit der doktor-chain einen Schritt
gemacht um die Technik herauszuziehen
aus dem Report Story
viele dieser Tools und doctool chain
wird leider oft auch mit static side
Generators verglichen haben die die
ganze Technik mit im Report Story
das haben wir jetzt geändert das war
nämlich auch immer so die Frage oh ja
das ist gerade drin das ist also nur für
für Java und jetzt ist da quasi nur noch
ein Rapper im repostory und der schaut
ob
Docker installiert ist ob er ein Docker
Image verwendet oder ob er es lokal in
User Folder installieren soll und
mittlerweile gibt es auch ein Kommando
get Java was dann die richtige Java
Version auch noch in den Doktor chain
Folder installiert und damit ist es
eigentlich unabhängig von der
Technologie ist natürlich in einer
Technologie in Java umgesetzt
aber ansonsten solltest unabhängig sein
und kann eben für alles mögliche
verwendet werden
genau noch mal ich gehe gleich darauf
ein noch ein kurzer Rücksprung magst du
noch einmal kurz so ganz kurz sagen was
mermaid überhaupt ist weil es hier Leute
sind die das noch nicht gehört haben
also ja mermaid ist ähnlich wie plant
URL ein 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 plant UML 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 companion
Docker Container der dann glaube ich per
headless Chrom das Image rausholt oder
sowas
aber es funktioniert und wenn man auf
kroki.io geht und dann sieht man eine
ganze Liste von solchen Diagramm Tools
die alle eben Text nach Diagramm wandeln
da gibt es auch
netzwerk-diagramme und auch ich glaube
Vega heißt es mega und mega Leid ist für
Standard Diagramme wie Peitsche bei
liniendiagramme und sowas
sehr gut jetzt tun wir so als hätten wir
die Anmerkung nicht gehört und wussten
noch über was es davor ging genau die
Frage mit dem gibt es das nur fürs Java
Ökosystem ich habe in Projekten die
Erfahrung gemacht das ganz oft die
Dokumentation eines eines einzelnen
Services gar nicht wirklich in diesem
Service liegt sondern das ist ein
separaten wird Ordner ein extra
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 das noch unabhängiger von der
eigentlich eingesetzten Sprache weil es
dann halt vollkommen egal ist ob der
Service sind da was gibt geschrieben ist
oder Ingo oder in ja genau
genau also ja das sieht man tatsächlich
sehr häufig dass ein Projekt über
verschiedene Report Stories verteilt ist
eine Architektur über verschiedene
Microsoft Services und ich denke es
macht durchaus Sinn das Jahr einer der
Vorteil von dem Doktors 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 weiterleben mit jedem
bauen der Dokumentation
und gerade weil dort Tool chain eben ja
ein config-pfeil und ein Rapper ist kann
ich diesen Rapper in jedes dieser
repostories legen um diese Report
Stories einzeln zu rendern
aber ich kann eben auch ein
übergeordnetes Architektur Report Story
aufmachen indem ich dann alles
zusammenziehe und ich mache das ganz
gerne mit einem einfachen geht Klone der
tiefer 1 dass ich eben ein kleines
Skript habe wo ich die anderen Report
Stories reinziehe und dann aus der
hauptdokumentation referenzieren kann
das funktioniert super und ich habe
ehrlich gesagt noch kein environment
Entwicklungs environment erlebt wo kein
Kind Client installiert war so dass
dieser Ansatz super funktioniert
an teurer ist ja auch noch mal so ein
static side Generator der coole Features
hat
nennt immer das als großes Feature das
die Dokumentation in verteilten
repostores liegen kann weil eben da ein
Javascript basierter gibt Client mit
dabei ist aber ich habe diesen Use Case
eben noch nicht gefunden da ich eben
extra geht klein brauche
aber da sagst du gerade noch was mit dem
static side Generator also wir sind
vorhin schon ziemlich oft auf dieses
wird generieren nach Konferenz gegangen
ich glaube auch das ist das was ich in
ihrem 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 ein oder zwei Jahre
hier ähm über Micro Sites für
Architektur Dokumentation und meine
Frage kann man mit der Doktor Jane auch
Micro sights generieren oder ist das
noch nicht wirklich doch also das ist
jetzt eigentlich mit einer der Haupt Use
Case die die ich benutze
ich kann tatsächlich es sind glaube ich
vier befehle ich habe meinen Tweet
verfasst wo sie drin sind da ich mit
einem Curl den Doktor chain Rapper ziehe
den executable mache dann durch den
Befehl Download Template aus mit dem ich
dann das Akt 42 Template mit mir die
aktuellste Version er fragt dann nur
noch welche Sprache und mit oder ohne
Hilfe und mit dem Befehl generate Zeit
baue ich da tatsächlich eine Microsoft
Seite auf mit Landingpage mit der
Dokumentation es ist sogar eine lokale
Suche mit dabei über Luna JS
und da wird jaybake als static side
Generator genutzt und JP kann eben was
geht ab und Markdown und HTML und über
das HTML Feature wird dann eben auch
restructure Text zum Beispiel
reingezogen dass man das noch mal extern
aufruft und nach HTML konvertiert somit
ist das eins der großen Features aber es
sind eben auch so Features dabei dass
ich dann eben auch PDF rauslassen kann
da ist nach Konferenz 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 ja auch ganz gerne so
ein Diagramm mit einer Tabelle wo ich
die Elemente noch näher beschreibe und
Doktor zum Beispiel Excel falls einlesen
nach asgok konvertieren und da der total
viele Features von dem excel-fall mit
die Spaltenbreite
Hintergrundfarben Word horizontal
Element soll 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 Fall wie mit den Image
Stifts das dadurch dass ich das eine
Textform rausgezogen habe kann ich dann
von dem Excel File tatsächlich den Stift
sehen und sehen was ich geändert hat
aber nur das also du würdest trotz also
ich würde das Excel-File pflegen und die
Pipeline würde dann die Informationen
aus dem Wechsel zu fallen in die Pool
Clan pusten und in der Transformation
von der Tool chain würde ich dann das
sehen also genau und das ist dann so ein
Punkt wo man eigentlich als Entwickler
sagt ja das Export also aus Excel
exportiert Tabelle das ist dann
eigentlich generiert und sollte
eigentlich nur ein Bild voller Leben
das Ganze kam aber als Paul request ich
weiß jetzt gar nicht mehr von wem rein
müsste man noch mal aussuchen
und derjenige hat das Ganze eben in den
Source Folder reingelebt da wo es eben
versioniert wird und wir hatten dann
eine kurze Diskussion ja sollte es nicht
eigentlich ein Bild voll da liegen der
hat gesagt nein weil die Versionierung
bringt eben den Vorteil dass ich machen
kann und dass ich eben sehe dass ich 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 weil und das
exportierte
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 ist klar dass man gerne Fragen
zu stellt
genau ich glaube rausgehört zu haben
dass du lieber plant omel machst als
draw.io stimmt das nein also
mittlerweile
plant URL ist toll fürs die können es
Diagramme weil da gibt's keine Layout
Probleme bei allem anderen die hier
schon gesagt worden ist 7 + -2 das ist
prima wenn ich Gefahr laufe des
komplexer wird dann sollte ich aufpassen
aber das plusminus 7 plus minus 2 das
tatsächlich ein guter Ansatz um
ja um übersichtliche Diagramme zu
erstellen also über die Zeit habe ich so
ein paar
Prinzipien mehr 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 Risiken 8k
Monitore sondern ich meine ein normalen
Notebook
Bildschirm
ohne Zoom und das bedeutet eigentlich
schon ich kann gar nicht so viel
Elemente draufsetzen sondern ich muss
auf einer gewissen abstraktions Ebene
bleiben bei einer gewissen Flughöhe und
da hilft von Simon Brown das C4 der C4
Ansatz dass ich ja auf der obersten
Ebene nur den Kontext darstelle nächste
Ebene gehe ich in die einzelnen
Container rein
von components die classis 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
net hat noch ein paar andere nette
Vorteile nicht nur für
architekturdiagramme zum Beispiel auch
wenn ich ein User Manual mache und mit
Screenshots arbeite und irgendwas
Highlighten will oder so
das ist auch so ein ja mindset dass man
mit einem Diagramm Tool mit Screenshot
arbeitet aber ich habe herausgefunden
ist ganz nützlich weil wenn ich den
Screenshot reinsetze und dann mit
Pfeilen oder Highlights arbeite oder so
dann habe ich eben source diese Pfeile
und Highlights getrennt vom Screenshot
und wenn ich das ganze dann irgendwann
mal aktualisieren muss neuer Screenshot
rein dann hänge ich einfach den
Screenshot rein und guck ob die Pfeile
noch passen
und das sind einfach Features die sind
die sind toll dabei
ja
Architektur Dokumentation noch nicht
sehr oft Screenshots gesehen genau
deswegen das ist dann eher so ein User
Manual oder so aber auch das hat man
teilweise mit zu arbeiten
der Screenshots in Architektur
Dokumentationen
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
Screenshot passend
genau du hast schon ganz oft gesagt und
wie Sequenzdiagramme und meine Frage
wäre was die Diagrammtypen sind die du
am häufigsten in Architektur
Dokumentationen einsetzt
ja eigentlich Boxen lines ne also gar
nicht so an den URL Diagramm entlang
hangeln sondern das was passt und wir
waren vorhin beim Enterprise Architekt
und das ist ein Feature was ich an ihm
Liebe dass man Elemente aus
verschiedenen Diagrammtypen
zusammenschmeißen kann weil ich eben
auch an ein Klassendiagramm mal ein
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 Arc 42 Template
das
bringt ja schon einige Vorschläge für
für bestimmte Diagrammtypen zusammen
und das sind dann eigentlich auch so die
groben Diagramm Typen 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
das es kommt nicht nur auf den Diagramm
Typ drauf an ob etwas lesbar ist sondern
eben auch wie ich das ganze Aufbau und
ich glaube es hat jeder schon diese
Diagramme gesehen
wo sehr viel weitspace 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 so dass wenn ich das ganze
Diagramm was zwar nur wenig Elemente hat
aber wenn ich es eben in einer Zoomstufe
habe dass ich eben komplett übersehen
kann dass dann eben die Schriften
teilweise zu klein sind da ich die nicht
mehr lesen kann und das ist zum Beispiel
auch so ein Ding wo ich sag da kann man
an Diagramm viel verbessern dass man
eben white space rausnimmt dass man die
Sachen enger zusammensetzt dass man auch
auf das optische achtet das ich mache
zum Beispiel ganz gerne dass die
Schriftgröße von den von den Blöcken
vergrößert teilweise fett machen damit
man das auf jeden Fall einfach lesen
kann und so Beschriftung von Teilen
kleiner mache weil das ist das man muss
erstmal 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
und da gibt es auch ein Talk eine
Aufzeichnung vom
Jochem Schulen Klopper und der geht
genau auf diese Sachen auf das visuelle
sehr stark ein und der 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 uns in Diagramm nicht so
ein nicht zum Beispiel an AWS Diagramme
denke ich glaube der ist drei bucket ist
rot warum ist der eigentlich rot sollte
ich den meiden oder
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
daran arbeiten
es bringt was
auch hatte ich mal ein Projekt wo ich
die Kästen so groß gemacht habe wie halt
die Beschriftung waren also wenn wenn
die Beschriftung der Name etwas größer
war dann braucht die bisschen mehr Platz
habe da also größeren Kasten genommen
und wurde dann sofort gefragt
warum ist jetzt dieser Kasten größer als
Jena und bei mir erst gar nicht so
bewusst dass das Leute da drauf 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 seinen Diagramm reinbringt
und in der Legende kann man zum Beispiel
auch die Quelle des Diagramms gleich
nennen und den den Autor dass man
Ansprechpartner hat dass man die Quelle
auch findet dass man was verändern kann
ist eben auch ganz wichtig und ich denke
es sollte man nur weglassen wenn man
eine
visuelle Sprache benutzt die auch
irgendwo anders definiert ist aber
selbst dann sollte man auf diese
Definition verweisen dass man sagen kann
hey wir benutzen hier den keine Ahnung
AWS diagram Style und hier findet ihr
den
aber dann würdest du auch in dieser
Legenden Tabelle 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 würdest das
schon nicht nur die 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 halt wichtig dass man
eben auch
damit arbeitet was intuitiv Sinn macht
also es gibt ja diese Spielereien wo man
so paar Farbnamen hat und Grün in blau
schreibt und solche Geschichten und das
verbirgt ja als würde genauso verwöhnen
wenn ich jetzt definieren würde ein
kleines Kästchen hat großkomplexität
Großes Kästchen hat kleine Komplexität
oder sowas und deswegen
ist gut das zu erklären ist wichtig das
zu erklären aber eben auch wichtig dass
man intuitive
Eigenschaften nimmt so dass wenn man die
Erklärung gelesen hat man sagt ah ja
okay das macht Sinn und jetzt weiß ich
rot ist das was wir verändern wollen
also ich finde das total also ich finde
es sinnvoll ich finde es auch cool mit
Farben zu arbeiten also ich mag es
buntes Sammlung wirklich auch einige
hier draußen schmecken merkt ich habe
aber gerade also so ich hätte Angst dass
man das ja auch schnell übertreiben kann
mit dieser also mit Farben und jetzt ist
zum Beispiel grün-weiß gestreift
bedeutet das und das und nachher hat man
viel zu umfangreiches Diagramm obwohl
vielleicht nur fünf Komponenten da drin
sind aber die Legende davon ist vier
Seiten lang was die einzelnen außen und
Abstufungen zu bedeuten haben
Frage a hast du sowas schon mal erlebt
und Frage B machst du wenn du ein
Diagramm entwirfst so ein zenity Check
das sowas vielleicht gerade nicht
passiert
ja sanity Check ist ein gutes Thema
Simon Brown hat eine Checkliste für gute
Diagramme die habe ich in einem Buch was
ich angefangen habe auf lean Pub was
noch nicht fertig ist mal übersetzt und
auch mit meinen Ideen noch erweitert da
kann man einiges an Checkliste machen
aber schon allein wenn man eine Legende
erstellt und das macht keinen Spaß
sondern Legende zu erstellen ja dann
denkt man sich manchmal brauche ich
diesen extra Linientyp wenn ich den
rausnehmen dann ist die Legende kleiner
dann also auch das hilft teilweise
und wenn man tatsächlich
so komplex eine eigene visuelle Sprache
erstellt dann macht es vielleicht Sinn
die er wird das Projekt oder das
Unternehmen mal zu definieren und nur
darauf zu verweisen aber sonst in den
meisten Fällen merke ich eigentlich
genauso wie die Anzahl der Elemente
sollte man eben auch die die Anzahl der
Bedeutung von Farben Linien Größen und
sonst was
reduzieren und da auf einem
abstraktionslevel bleiben und
dann macht es vielleicht Sinn eben
mehrere Diagramme aufzubauen die eben
verschiedene Sachen darstellen
also wenn ich zum Beispiel ein
Kontrollfluss darstelle dann werde ich
nicht die Farben noch dazu verwenden von
den Elementen um zu sagen an dem Element
müssen wir arbeiten sondern dann ist
halt der kontrollbeschluss im Fokus
das ist übrigens auch so ein Ding die
die Richtung der Pfeile in den Diagramm
sind manche Sachen wo ich selbst früher
irgendwie drüber gestolpert bin was ich
mittlerweile als trivial ansehe aber die
Pfeilrichtung ich habe früher immer so
überlegten in welche Richtung mache ich
die Pfeile da wo die Daten hinfließen
dann rufe ich irgendwas auf und kriegt
Daten zurück also Daten rückrichtung
aber dann habe ich irgendeine API wo ich
ziemlich viel hinschicke und auch wieder
zurückbekommen und dadurch hatte ich
dann oftmals Pfeile die einfach in beide
Richtungen gezeigt haben und das hat
irgendwie gar keinen Mehrwert gegeben
bis ich mal mit Peter ruschka gesprochen
habe und der gesagt hat du es ist doch
klar es geht darum wer ruft wen auf ja
und ja seitdem ist dieses Problem aus
meinem Kopf raus ist hört sich albern an
wenn man es eben weiß aber es sind
genauso wie die das eben manche Leute
auf die größte der Elemente achten
hat mir dieser Hinweis einfach extrem
geholfen und trotzdem schreibe ich es in
die Legende rein in kleinen Pfeil und
daneben Aufruf Richtung und damit ist
das eben klar
ich muss mal einmal hier einen Anmerkung
an die Youtube Jan und Tobias Höft
machen ihr habt einmal geschrieben denkt
jeden keine Informationen übers Internet
und Beispiel der Youtube Chat ist leider
für uns ein bisschen versetzt also wir
sind ein bisschen vor eurer Zeit sagt
man das so hört sich blöd an wenn ihr
wollt dass ich dem Reifen Fragen stelle
dann wäre es total cool wenn ihr die so
ausformuliert dass ich sie jetzt stellen
könnte ohne den genauen Kontext zu haben
weil mir der schon fällt wenn ich euren
Text lese genau das wollte ich nur
einmal als Anmerkung sagen ich glaube
die Anmerkung mit den Informationen über
das Internet bezieht sich wahrscheinlich
auf den Cookies Server weil wenn man
jetzt eben für die Dokumentation für das
Rendering der Diagramme den Cookies aber
im Internet nimmt
ist das natürlich blöd dann gehen da die
Infos über das Projekt irgendwo raus
was ganz nett ist ist dass der Kroki
Server plant ulml kompatibel ist das
heißt für Plantur mehr gibt es eben auch
ein entsprechenden Server und
gitlab nutzt diesen Plan du Mail Server
und den kann ich eben gegen den Cookie
Server austauschen in meiner
Organisation so dass eben gitlab plant
Ulm über den Server rendert aber eben
ich dann auch diesen Cookie Server für
andere Diagrammtypen habe
und damit kriege ich den relativ leicht
aufgesetzt also wenn ich ein getlep Team
habe dann
bitte ich die einfach die Komponente
austauschen
möglicherweise war das die Antwort auf
ganz anderem genau
du hattest eben das fand ich ganz
interessant
öfter mal darauf verwiesen dass es ja
vielleicht schon eine visuelle Sprache
im Unternehmen gibt die man nutzen kann
oder eben nicht und man führt einer ein
würdest du sagen dass es mein Ziel als
softwarearchitektin die total
Visualisierung und Dokumentation liebt
sein sollte eine visuelle Sprache in
einem Unternehmen einzuführen die dann
derer sich dann andere auch bedienen
können
ich weiß nicht ob so das direkte Ziel
sein muss aber ich kenne das häufig dass
Vater ausgetrampelt werden dass das was
gut ist von anderen übernommen wird und
wenn man eben so eine gute visuelle
Sprache aufsetzt in einem Projekt und
andere die sehen dann wird die
wahrscheinlich übernommen werden
und ich glaube so ergibt sich das
einfach natürlich macht es auch Sinn
wenn man dann eben mal drüber spricht
dass man sagt hey ich hatte hier immer
visuelle ja Probleme mit dem visuellen
Styling das sehr ähnlich bei bei
planturml wenn man da
den Style nicht mag und einen eigenen
Style aufsetzt dass der dann eben durch
die Teams die Runde macht und mehrere
den verwenden
und ich glaube ähnlich ist das bei dem
visuellen Style von architekturdiagramm
natürlich macht es dann auch Sinn
vielleicht mal so ein bisschen Best
Practice aufzuschreiben und ich glaube
so eine Checkliste von Simon Brown oder
aus dem Docs Code Buch was nicht fertig
ist
die macht da auch Sinn
es ist noch nicht fertig
ich glaube fest an Dich ich auch
es macht übrigens auch Spaß wenn man
sich einfach mal
zusammensetzt und aus dem Internet mal
nach architekturdiagramm Google
in der Bildersuche ein Diagramm
rauspickt und in der Gruppe drüber
diskutiert was an dem Diagramm gut ist
was verständlich ist und was
unverständlich ist und dann eben auch so
fragen ja wärst du jetzt Architekt wie
würdest du jetzt mit diesem Diagramm
arbeiten könntest du es verändern zum
Beispiel auch
oder
ja dass man mal guckt welche
Informationen man daraus zieht
oftmals ist es auch so dass so ein
Diagramm etwas unverständlich ist aber
man sich gar nicht
traut da Kritik zu äußern weil man
denken ja also da wird sich schon
irgendwer was bei gedacht haben das S3
bucket immer rot ist das
wird schon irgendwie visuelle Sprache
sein die ich halt nicht kenne
links also genau mit dem Zusammensetzen
finde ich gerade noch interessant es
gibt ja in vielen Organisationen diese
Idee von es hat immer andere Namen Trips
chapters
ich weiß nicht unendliche Mengenangaben
wo sich Menschen aus verschiedenen Teams
die eigentlich an den gleichen Dingen
arbeiten z.B UX oder Architektur
zusammensetzen und über Dinge
diskutieren denkst dass ergibt Sinn
einen Trip für oder was auch immer wie
wie es auch immer genannt wird für
Dokumentation speziell zu machen wo man
sich einmal im Monat hinsetzt und
Diagramme anschaut die vielleicht nicht
gelungen sind oder überhaupt in der
Dokumentation spricht oder sowas
in der Tat ich denke das macht Sinn und
das ist auch dass sie der Doktors Code
Ansatz weiterentwickelt wird und eben
auch dorthin weiterentwickelt wird und
das macht durchaus Sinn sich das Ganze
anzugucken und zu gucken wo kann ich
hier jetzt
ich sag mal viele dieser Sachen zum
Beispiel diese
Enterprise Architekt Export ja der der
wäre nie so entstanden wenn ich mir
nicht gesagt hätte den kann ich für
mehrere Projekte gebrauchen in einem
Projekt hätte man gesagt nee das zu viel
Aufwand macht es nicht
aber wenn ich mich dann eben in mehreren
Projekten darüber Ärger das wäre
leichter wenn ich das exportieren könnte
und mich dann dran setze dann dann hat
es so einen Mehrwert und deswegen ist
dieses zentrale darüber nachdenken wie
können wir das verbessern und auch das
Plugin ist ist so ein Beispiel dass
ja in einem Projekt für das Projekt
hätte man es nie gemacht aber jetzt
benutzen es ganz viele auch wenn es noch
so ein bisschen
ja es hat noch Verbesserungspotenzial
wenn ich zum Beispiel in der
standardzoomstufe ein PNG erstelle dann
ist es ein bisschen pixelig ist die
Auflösung für die Schrift nicht so gut
deswegen ziehe ich meine ganzen Elemente
erstmal auf 200% hoch und nehmen auch
anstatt 12 Punkt Schrift 24.schrift
dann ist das gelöst passt da jemand mal
Lust hat an das Plugin Rand zu gehen
ja wir würden uns freuen
genau ein Thema was damals mit falschen
Auftrag haben was glaube ich mit
genereller Architektur Dokumentation
noch einfacher zu beheben ist als mit
Diagrammen aber vielleicht hast du da
auch eine Lösung für ist die Diagramme
in der Architektur Dokumentation aktuell
zu halten hast Du spezielle
Vorgehensweisen wie das gewährleistet
bleiben kann
also ein wichtiger Punkt ist natürlich
dass man überhaupt weiß wo die Quellen
des Diagramms liegen dass man damit
arbeiten kann
der nächste Punkt haben wir ja auch
schon angesprochen dass ich eben weiß
wie ich
dann auch die aktualisierten Diagramme
in die Dokumentation reinbekommen das
heißt besser in der Dokumentation sind
die Diagramme referenziert das übrigens
ein Feature was auch eine
Textbearbeitung kann sie sie kann
externe Diagramme reinziehen dann wäre
das Ganze leichter damit zu arbeiten
aber es ist halt ein Feature was von
vielen nicht genutzt wird und spätestens
wenn dann eben nur das Hauptdokument per
E-Mail verschickt wird dann sagen alle
das funktioniert so nicht
aber wichtig ist auch genauso wie bei
der restlichen Architektur Dokumentation
das meinen ein
abstraktionslevel erwischt der sich
selten verändert so dass man eben weiß
das hat jetzt längere Zeit Gültigkeit
und wenn wir an die Definition von
Architektur denken dass das die
Entscheidung sind die eben später
schwierig sind zu verändern die
tragenden Mauern unseres Gebäudes die
reißt sich nicht einfach noch mal ein
wenn ich die
ja die Position eines Sofas in im
Wohnzimmer dokumentiert naja dann dann
muss ich das ständig aktualisieren aber
das sollte eigentlich eben auch nicht
Teil der Architektur sein
ich frage mich oft drin im Wohnzimmer
umräumst dass unser so versteht er
einfach steht Seite ewig aber okay
ja es ist zum Beispiel jetzt musste das
Sofa dem Weihnachtsbaum irgendwie
weichen
und dann kann das schon woanders stehen
die Architektur Dokumentation fürs
Wohnzimmer temporär angepasst werden das
wäre ja dann die Innenarchitektur und
also das sind halt wirklich wichtige
Punkte und dieser Ansatz dass ich die
Quellen bei dem stop net
Diagramm habe das ist super klasse
und ich sollte halt auch wirklich bei
allem was ich in die Diagramme
reinschreibe darauf achten welche
Details ich rein schreibe und das das
sehe ich eben auch immer wieder bei
Diagramm wenn da irgendwo eine Pfeil
eine Portnummer dran steht
ja es gibt Standardports aber ansonsten
ist das eigentlich den Betriebsteam
überlassen auf welchen Port irgendein
microservice läuft oder sowas und
teilweise sehr mittlerweile auch
dynamisch oder ich weiß dass in der
Information die veraltet viel zu schnell
dann schreibst lieber nicht dran
noch einmal noch warum habe ich das
gerade gefragt mit dem aktuell auf
Twitter kam der kommentar von stefan
Hildebrandt aktuell sollten sie sein und
Zugriff auf historisches ist manchmal
auch gut also zu architekturdiagramm das
historische haben wir schon abgebildet
mit dem wir haben es geht genau unter
Aktuell hast du jetzt gerade noch mal
erklärt wir neigen uns langsam dem Ende
der Zeit Ralf und ich glaube du möchtest
ganz bestimmt noch Werbung machen für
alle Leute die richtig Lust haben sich
noch mehr mit Architektur die
Dokumentation zu befassen und zufällig
im März ist es ne aber genau
ja auf der javaland werde ich mit Falk
sippach das Thema noch mal
noch mal aufbereiten dass wir
tatsächlich noch mal über Diagramme
fantastische Diagramme haben wir jetzt
genannt sprechen werden und all diese
Dinge die wir jetzt mal so angeschnitten
haben noch mal zusammen suchen dass wir
über das visuelle hergehen dass wir aber
auch über die Wartbarkeit hergehen und
noch mal in einem längeren Talk das
ganze erklären slides haben werden dass
man dann auch im Nachgang noch mal das
ganze sich angucken kann auf der
javaland und ich glaube da werden wir
viel Spaß haben nicht nur beim
Achterbahn fahren
genau ich habe glaube ich doch noch eine
Frage weil wenn ich die Chance nutzen
will bevor wir aufhören und zwar also
ich finde die Idee cool den
Ersteller des Diagramms dran zu
schreiben weil ich dann weiß wen ich
ansprechen muss
erhöht aber gefühlt auch den busfaktor
für Diagramme weil man sich dann darauf
also ich habe Angst dass alle im Team
sich auf dich verlassen weil du bist der
Reif du rennst rum und erzählst über
Diagramme du machst die halt auch und
jetzt bist du vier Wochen im Urlaub oder
oder was auch immer oder auf all den
Konferenzen wo du so rum tust ähm
bleiben die Sachen dann liegen oder habt
ihr das im Team irgendwie geschafft das
nicht nur du dieser ich sag mal Diagramm
Heidi bist oder Dokumentation zeigen da
kommt dann auch wieder der Doktors Code
Ansatz zu tragen und ich finde das total
spannend ich habe zuerst bei der
Microsoft Dokumentation gesehen
dass die eben auch raus Rendern wer an
diesem Teil der Dokumentation gearbeitet
hat über die Quests
und ich habe erst gedacht so von wegen
ach ja das ist ja eigentlich ganz nett
das ist noch mal so eine Anerkennung
dass die Leute mit dran gearbeitet haben
und Gernot brachte mich dann auf die
Idee dass das mehr ist dass mir das eben
auch als lesender hilft da ich sehe wer
hat sich eigentlich mit diesem Teil der
Dokumentation mal beschäftigt das heißt
wenn da jetzt ich sag mal der der Lied
Architekt als Gärtner an dem Diagramm
dran steht dann fährt man trotzdem
hoffentlich den Ina sourceansatz oder
vielleicht sogar Open Source Ansatz für
die Architektur Dokumentation und es
haben mehr Leute an dem Diagramm oder an
der Dokumentation drumherum gearbeitet
so dass man dann eben an den Comments an
der Historie sehen kann wer hat da
vielleicht noch Ahnung von
und somit ist dann der busfaktor etwas
kleiner guter Tipp mit der gitis auf
jeden Fall ja genau also wir sind
wirklich knapp vor Ende der Zeit und ich
Ende immer super gerne mit so einem Tipp
oder so also ich würde mir von dir einen
Tipp wünschen wie ich ab morgen meine
architekturdiagramme verbessern kann
das ist ganz schwierig so ein knackigen
Tipp ich sage immer einfach mal anfangen
und vor allem das
Plugin für Visual Code oder intellijay
angucken und damit macht das total viel
Spaß gute saubere Diagramme herzustellen
und sie eben auch aktuell zu halten
ja genau dann würde ich sagen vielen
vielen Dank dass du heute hier warst
Ralf vielen Dank an euch da draußen dir
zugeschaut habt und Fragen gestellt habt
und mitgemacht habt oh jetzt hat kam
gerade noch eine Frage muss ich noch
bestellen weil cockaggi auf Twitch fragt
welches Plugin
wir sind jeweils nur für beide Plattform
ein Plugin bekannt
bewusst.net und wird ein Plugin finden
und das ist genau das ist tatsächlich
ein Punkt auf frisches glaube ich dass
draw io Plugin und intelligentes
diagrams.net Plugin
official Codes von dem Henning
dieterichs und äh auf diverse auf
intelligente habe glaube ich ich das als
hauptmentainer eingecheckt
müssten aber alexander Schwarz und
Henning mit dabei stehen
jetzt aber genau sehr gute Frage dann
vielen vielen Dank dass du da warst Ralf
vielen Dank dass ihr da draußen da war
sehr gerne und genau wir gehen jetzt
quasi offline bis ins neue Jahr und
wünschen euch schöne Feiertage einen
hoffentlich erholsamen Urlaub wenn ihr
welchen habt einen guten Rutsch ins neue
Jahr und wir freuen uns darauf Euch
nächstes Jahr dann wieder begrüßen zu
können genau dann bis bald ciao
関連動画をさらに表示
Introduction to UML
UML Diagram For Software Engineering | Unified Modelling Language Diagram | Simplilearn
Visualising software architecture with the C4 model - Simon Brown, Agile on the Beach 2019
Project Based Internship Klinikgo Health System Analyst - Company Coaching Video 1
Five Things Every Developer Should Know about Software Architecture • Simon Brown • GOTO 2020
Como descomplicar seu processo de não conformidades com o Qualiex
5.0 / 5 (0 votes)