Mehr als Pfeile und Kästen: Architekturdiagramme mit Ralf D. Müller und Lisa Moritz

Summary

In 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

00:00

🤝 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.

05:03

📈 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.

10:03

🔄 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.

15:03

📊 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.

20:07

🌐 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.

25:07

🔧 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.

30:08

📚 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.

35:09

🎨 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.

40:11

🌈 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.

45:13

🔄 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.

Keywords

💡Software Architecture

The term 'Software Architecture' refers to the structure of a software system, the discipline of creating such structures, and the documentation of these structures. In the context of the video, it is the central theme, with the guest Ralf Müller discussing his role as a Chief Architect and his focus on architecture documentation.

💡Architecture Documentation

Architecture Documentation is the process of creating, maintaining, and presenting the structural description of a software system. It is a critical aspect of software engineering that helps in understanding the system's design and functionality. Ralf Müller emphasizes the importance of keeping documentation up-to-date and his journey towards automating this process.

💡docToolchain

docToolchain is an open-source project initiated by Ralf Müller for automating the process of creating and maintaining architecture documentation. It allows for the integration of diagrams and other artifacts directly into markdown documents, making the documentation process more efficient and less error-prone.

💡UML Tools

UML (Unified Modeling Language) Tools are software applications that provide graphical representations for modeling and designing software systems. They are used to create diagrams that illustrate the structure and behavior of a system, such as class diagrams, sequence diagrams, and more.

💡Enterprise Architecture

Enterprise Architecture is a holistic approach to understanding and designing the business processes and IT systems of an organization. It provides a blueprint for the organization's IT infrastructure and demonstrates how it supports the business strategy.

💡PlantUML

PlantUML is a tool that allows users to create UML diagrams from a simple textual description. It is often used for generating diagrams in documentation due to its ability to convert text descriptions into visual diagrams, making it a valuable tool for software architects.

💡Version Control

Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. It is essential for tracking the evolution of documentation and diagrams, ensuring that the most up-to-date information is available.

💡Visual Communication

Visual communication is the conveyance of ideas and messages through visual means, such as diagrams, charts, and images. In the context of software architecture, it is crucial for explaining complex system designs and functionalities in a clear and understandable way.

💡Open Source

Open Source refers to a software system or project whose source code is made available to the public, allowing anyone to view, use, modify, and distribute the code. It promotes collaboration and community involvement in the development and improvement of software.

💡Architecture Diagrams

Architecture Diagrams are visual representations of the structure and components of a software system. They are essential tools in software architecture for communicating the design and relationships between system elements.

💡Collaboration

Collaboration refers to the act of working together with others to achieve a common goal. In the context of software architecture, it involves team members from different disciplines, such as developers, architects, and stakeholders, to design, review, and refine the system's architecture.

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