Architekturdokumentation & -Kommunikation
#gleichrichtigmachen
Unbeliebte Arbeit, aber riesiger Mehrwert für Teams und System
Die Entwicklung von Softwaresystemen sind große und herausfordernde Vorhaben. Es müssen komplexe Strukturen und Lösungskonzepte entworfen werden, diese umgesetzt und die Systeme qualitätsgesichert, betrieben und gewartet werden. Teams, die an der Konstruktion und Umsetzung eines Softwaresystems arbeiten, müssen ein gutes Verständnis und gemeinsames Bild des Systems haben, denn nur so ist ein Ergebnis von hoher Qualität möglich. Eine Dokumentation der Architektur des Systems bildet dafür die Grundlage. Sie dient sowohl als persistenter Informationsspeicher, hilft Ideen zu präzisieren und dient als Kommunikationsmedium zwischen Teammitgliedern. Das macht Architekturdokumentation unverzichtbar.
Dennoch wird Architekturdokumentation in Projekten häufig vernachlässigt. Das liegt sowohl daran, dass unter Zeitdruck gerne Dokumentation geopfert wird, um gefühlt schneller ans Ziel zu kommen, als auch daran, dass viele Personen mit technischem Hintergrund einfach lieber Code als Dokumentation schreiben. Insgesamt leider eine wenig nachhaltige und mittelfristig sehr teure Praxis.
Das Gute ist, eine unpassende Architekturdokumentation lässt sich sehr viel schneller verbessern als eine unpassende Architektur. Und die Investition in sauberes Engineering und eine gute Dokumentation lohnt sich, denn die Vorteile durch eine zielgerichtetere Umsetzung und durch ein langlebigeres System auf Basis durch klare Strukturen und durchdachten Ansätzen wiegen die Zeitinvestition vielfach auf.
Leider fällt es vielen Menschen schwer, eine gute Architekturdokumentation zu schreiben. Zwar gibt es Vorlagen, die den Start erleichtern sollen, dennoch bleiben dadurch viele Fragen offen und die Umsetzung für das eigene System häufig eine Herausforderung. Wir helfen unseren Kunden, die Architekturen ihrer Systeme herauszuarbeiten und so zu dokumentieren, dass sie einen möglichst großen Mehrwert für das Vorhaben entfalten. Über unsere Erfahrungen, Tipps und Tricks für Architekturdokumentation schreiben wir regelmäßig Beiträge für unseren Blog. Diese erstrecken sich von den Grundlagen über die Strukturierung bis zu Details von einzelnen Diagrammelementen. So wollen wir anderen helfen, gut geeignete Architekturdokumentationen zu schreiben und im Projekt besser voranzukommen.
Architekturdokumentation aus der Praxis: Warum Dokumentation?
Wenn Ihr jetzt noch nicht überzeugt seid, dass gute Architekturdokumentationen eine absolute Notwendigkeit sind, dann lest unsere Brandrede für Architekturdokumentation. Hier berichten wir von unseren Beobachtungen zum Zustand von Architekturdokumentation, motivieren ausführlich, warum es gute Architekturdokumentationen braucht, und geben einige Tipps zur Arbeit an Architekturdokumentationen. Außerdem appellieren wir an unser Arbeitsethos als Software-Ingenieure, Dokumentation als wichtigen Teil unserer Arbeit anzusehen. So muss sich unser Qualitätsanspruch an unsere Arbeitsergebnisse, eben auch auf Architekturdokumentation erstrecken. Also, los geht’s, Architekturdokumentation ab jetzt in gut.
uch wenn wir uns dafür stark machen, Architekturdokumentation als Teil der Arbeit von Software-Ingenieuren zu begreifen, sehen wir ein, dass Dokumentation zu schreiben nicht jedermanns Sache ist (was nicht heißt, dass man es dann lassen sollte). Insbesondere der Anfang, wo es darum geht, eine solide Struktur aufzubauen und die wichtigsten Konzepte und Funktionsweisen präzise und kohärent zu beschreiben, fällt Vielen schwer.
Deswegen schlagen wir eine Rolle vor, die in solchen Projektsituationen helfen kann: Den „Architektur-Phantombildzeichner“. Angelehnt an Phantombildzeichner aus der Kriminalistik spricht sie mit den unterschiedlichen Stakeholdern im Projekt, findet die wichtigsten, architekturrelevanten Informationen heraus und erstellt basierend darauf eine Architekturdokumentationen, die die Grundlage für die künftige, gemeinsame Arbeit daran bildet. Der Artikel stellt die Rolle des Architektur-Phantombildzeichners ausführlich vor, beschreibt dessen Aufgaben und notwendige Skills und gibt konkrete Tipps zum Vorgehen. Es ist bestimmt keine Rolle für jede:n, aber eine mit großem Einfluss und Mehrwert; und die Freude und Dankbarkeit des Teams kann einem fast sicher sein.
Gute Doku, dankbares Team: Phantombildzeichner für Softwarearchitektur!
System schlägt Template: Wider Schema F bei Architektur-Dokumentationen
Sichtbar bessere Architekturdokumentationen
Architekturdokumentation niemals aus Büchern abschreiben!
Architekturdokumentation aus der Praxis: Kontextabgrenzung
Dein Konzepte-Kapitel ist zu kurz. Arbeite dran.
Hier bekommt ihr Tipps bis auf die Detailebene. In diesem Artikel diskutieren wir Pfeile und deren Verwendung in Architekturdiagrammen. Es geht um Pfeil-Arten, Beschriftungen, Pfeilrichtungen, Pfeilquellen und -Ziele. Anhand von zahlreichen Beispielen geben wir Tipps und Hinweise, wie Pfeile in Architekturdiagrammen so verwendet werden können, dass ihre Bedeutung deutlich wird und sie damit zu einer klaren Beschreibung des Systems beitragen.
Wie man einen Pfeil malt
