Anja Kammer & Stefan Zörner 08. Oktober 2024

Infrastruktur in der Architekturdokumentation

Die Prinzipien guter Architekturdokumentation sind den meisten bekannt. Doch die Infrastruktur bleibt dabei oft unbeachtet oder wird sogar nur von wenigen "Wissenden" verstanden. Gerade bei komplexen Systemen ist das Festhalten von Lösungskonzepten und Entscheidungen auf der Infrastrukturebene einer Anwendung wichtig, um die Architektur nachzuvollziehen und die Software weiterentwickeln zu können. Dieser Beitrag richtet sich an Entwicklungsteams, die Schwierigkeiten haben, Infrastrukturthemen in ihre Dokumentation zu integrieren. Er bietet zudem Einsichten für Platform Engineers und crossfunktionale Teams, die ihre eigene Infrastruktur verantworten.

Unter Infrastruktur verstehen wir in der Software-Entwicklung etwas vereinfacht alles, was eine Anwendung so "zum Leben braucht". Und was Entwicklungsteams, anders als fachliche Funktionalität, üblicherweise nicht selbst verantworten. Analog zur Infrastruktur einer Stadt wie ÖPNV, Strom und Wasser fallen hierunter z. B. Netzwerke, Speicher- und Rechenkapazitäten, aber auch API-Gateways und Messaging Middleware, wobei sich letztere mit dem Begriff Anwendungsinfrastruktur abgrenzen lassen.

Immer mehr Unternehmen erkennen die Vorteile autonomer Entwicklungsteams, die sich um den gesamten Software-Lebenszyklus kümmern, einschließlich der Verantwortung für den Betrieb. Allerdings stößt ein Großteil der Unternehmen damit eben auch auf die Belastungs- und Kompetenzgrenzen ihrer Entwicklungsteams. Um diese Probleme zu beleuchten und geeignete Maßnahmen vorzuschlagen, haben wir uns ein kleines Fallbeispiel ausgedacht.

Ausgangssituation

Die MakeItSure GmbH ist ein führender Anbieter digitaler Lösungen in der Versicherungsbranche. Ihr Hauptprodukt "CoverFlex" ist ein Versicherungskonfigurator, der es den Versicherungsnehmern ermöglicht, maßgeschneiderte Policen in Echtzeit zu erstellen und anzupassen. CoverFlex bietet eine benutzerfreundliche Oberfläche, die es sowohl Privatpersonen als auch kleinen und mittelständischen Unternehmen erlaubt, individuelle Versicherungsprodukte nach ihren spezifischen Bedürfnissen zu konfigurieren.

Der Versicherungskonfigurator wird von sieben spezialisierten Entwicklungsteams betreut, die an insgesamt 16 fachlichen Modulen bzw. Services arbeiten. Diese Services decken alle Funktionalitäten ab, von der Policenverwaltung und Risikobewertung bis hin zur Integration von Partnerdiensten.

Abb. 1: Entwicklung und Betrieb des Produktes CoverFlex, schematische Darstellung nach der Modernisierung. © embarc // INNOQ

Angesichts der wachsenden Komplexität durch die Internationalisierung im europäischen Raum und des Fachkräftemangels im IT-Betrieb entschied sich die MakeItSure GmbH vor zwei Jahren, eine umfassende Modernisierung ihrer IT-Systemlandschaft durchzuführen. Während zuvor alle Systeme On-Premises betrieben wurden, fand eine teilweise Verlagerung in die Cloud statt. Durch die Nutzung von Public Cloud Services kann das Unternehmen die Arbeitslast im Betriebs-Team stabil halten, selbst bei dieser neuen hybriden Infrastruktur-Architektur.

Diese Modernisierung umfasste nicht nur die technische Infrastruktur und die Architektur der Services, sondern auch die Anpassung der Entwicklungs- und Betriebsprozesse an die neue Cloud-Architektur. Software wird mittels Containern ausgeliefert und die nötige Infrastruktur mit Infrastructure-as-Code-Tools automatisch provisioniert und konfiguriert. Auch die Test- und Build-Pipelines sind nun Container-basiert und die Konfiguration wird von den Entwicklungsteams übernommen. Außerdem sind sie nun selbständig für ihre Deployments und das Monitoring ihrer Anwendungen verantwortlich. Das Betriebs-Team unterstützt sie dabei, indem es CI/CD-Infrastrukturen bereitstellt, Templates für die Pipelines erstellt und beratend zur Seite steht. Zusätzlich kümmert sich das Betriebs-Team um die zugrunde liegende Monitoring-Infrastruktur und querschnittliche Services wie Service Discovery, Routing und Messaging. Abb. 1 stellt die Situation schematisch dar. Entwicklungsteams genießen nun also eine große Autonomie und Flexibilität, insbesondere in ihren Architekturentscheidungen. Sie können mit Cloud-Services das jeweils beste Tool für ihre spezifischen Anforderungen auswählen.

Herausforderungen und Probleme

Mit dieser Modernisierung hat sich das Unternehmen seine Zukunftsfähigkeit auf dem Markt gesichert, und dennoch haben sich nach einiger Zeit Probleme manifestiert, die bis zur Geschäftsführung sichtbar wurden. Die Auslieferung von neuen Features verzögert sich und auch Incidents scheinen inzwischen häufiger aufzutreten, sodass es langsam unangenehme Nachfragen durch ihre Kunden gibt. Angesichts dessen hat die Geschäftsführung einen gemeinsamen Painstorming-Workshop von Betrieb und Entwicklung initiiert, um den Dingen auf den Grund zu gehen. Abb. 2 zeigt ein Zwischenergebnis aus dieser Veranstaltung, in der die Teams zunächst "Schmerzen" gesammelt haben, ohne sich zu voreilig auf die Lösungsebene zu begeben.

Abb. 2: Ein paar Beispiele für "Schmerzen" der beteiligten Teams. © embarc // INNOQ

Painstorming hat zum Ziel, aktuelle Probleme und Hindernisse in Prozessen und der Zusammenarbeit aufzudecken. Schließlich konnten die Teams vier große Problem-Cluster im Workshop herausarbeiten, die für viele kleine und große Schmerzen in der Entwicklung und im Betrieb sorgen:

Deployments als "Heiße Eisen": In manchen Entwicklungsteams hat es sich etabliert, neue Änderungen zu sammeln, statt sofort zu deployen. Unerfahrenere Mitglieder trauen sich oft nicht, selbst zu deployen, aus Angst, bei Fehlern im Rollout keine Lösungen parat zu haben. So wird die Deployment-Verantwortung oft auf diejenigen verschoben, die bereits Erfahrung in Infrastruktur und Deployment haben oder unter Druck stehen, zeitnah neue Änderungen auszurollen. Das Sammeln vieler Änderungen über die Zeit macht es allerdings immer schwerer, die Grundursache eines fehlgeschlagenen Deployments zu ermitteln.
Fragile Deployments: Andere Entwicklungsteams dagegen handhaben Deployments wie vor der Modernisierung. Anstatt kontinuierlicher Auslieferung finden Deployments weiterhin nur alle paar Monate statt. Diese Deployments sind oft große Ereignisse, die das gesamte Entwicklungsteam für einen Tag in Anspruch nehmen und punktuelle Unterstützung des Betriebs-Teams erfordern.
Konservative Architekturentscheidungen: Viele Entwicklungsteams zögern, neue Infrastruktur- und Architekturentscheidungen zu treffen und neigen dazu, jede Herausforderung mit ihrem bestehenden Tech-Stack anzugehen. Beispielsweise lassen sie regelmäßige Datenverarbeitungs-Prozesse in einer Webapplikation laufen, obwohl es in vielen Fällen eine gute Idee wäre, diese als kurzlebige, getimte Jobs durch die Betriebsplattform ausführen zu lassen. Ein anderes Beispiel ist das Speichern von Bildern als Blobs in der Datenbank. Dabei könnte gerade ein Object-Store als Lösung passender sein. Konservative Architekturentscheidungen mögen kurzfristig effizient und risikoarm erscheinen, führen aber langfristig zu höheren Betriebskosten und fragilen Anwendungen, die nicht optimal auf die jeweiligen Herausforderungen abgestimmt sind. Diese Anwendungen beinhalten häufig Workarounds und Eigenentwicklungen, obwohl der Cloud-Provider bereits passende Lösungen anbietet.
Dokumentationsdefizite: Ein großes Problem ist die stark fragmentierte, veraltete und schwer auffindbare Dokumentation. Es gibt unzählige verteilte Readme-Dateien und Markdown-Dokumente in Code-Repositorys und File-Servern sowie Wiki-Einträge. Doch Letztere sind oft auf andere Zielgruppen zugeschnitten, wie die Produktentwicklung. Die direkte Unterstützung durch das Betriebs-Team wird zwar geschätzt, jedoch fehlt diesem oft die Zeit, um bei wichtigen Infrastruktur- und Architekturentscheidungen umfassend zu beraten. Dies führt dazu, dass die Entwicklungsteams den Eindruck haben, die volle Verantwortung für den Betrieb ihrer Anwendungen zu tragen, während sie gleichzeitig auf implizites Bestandswissen und Inselwissen einzelner Personen angewiesen sind. Dies lässt sie mit ihren Problemen oft allein und behindert die Konzentration auf die Implementierung der Fachlichkeit.

Die Geschäftsführung zeigte sich erleichtert über die Ergebnisse, denn die Teams scheinen offen über ihre Schmerzen und Probleme geredet zu haben. Ein erster, wichtiger Schritt ist damit getan. Als Nächstes beauftragt die Geschäftsführung nach einer Diskussion mit den Beteiligten die erste Maßnahme, um die gefundenen Probleme schrittweise anzugehen: die Gründung eines virtuellen Plattform-Teams.

Maßnahme: Gründung eines virtuellen Plattform-Teams

Die Ergebnisse des Painstorming-Workshops haben gezeigt, dass den Entwicklungsteams zunehmend Verantwortung übertragen wurde, ohne dass ihnen gleichzeitig ausreichend Unterstützung zur Verfügung gestellt wurde. Um ihre Arbeit zu erleichtern, betrachtet das Unternehmen seine Entwicklungsteams künftig als interne Kunden und gründet deshalb ein Plattform-Team. Ein Konzept, das durch das Buch "Team Topologies" große Aufmerksamkeit erlangt hat [1].

Dieses neue Team bietet gezielt unterstützende Leistungen an, wie die Bereitstellung von Vorlagen und Anleitungen, die den Entwicklungsteams bei wiederkehrenden Problemen und Anforderungen als Handlungsleitfäden dienen. Des Weiteren übernehmen sie den Betrieb der Anwendungs-Infrastruktur, z. B. für Monitoring, Routing und Messaging. Allerdings ist eine ihrer ersten Aufgaben, eine Dokumentations-Initiative voranzutreiben.

Die Geschäftsführung hat sich für die Gründung eines virtuellen Plattform-Teams entschieden. Dabei müssen keine Mitglieder neu eingestellt werden oder ihre bestehenden Teams verlassen. Man kann es mit einer Community vergleichen, die sich regelmäßig trifft. Jedes Mitglied übernimmt Aufgaben und sie vertreten die Interessen ihres eigentlichen Ursprungsteams. Die Mitglieder des virtuellen Plattform-Teams kommen aus dem Betriebs-Team und auch zwei interessierte Entwickler:innen haben sich gemeldet, Teil des Plattform-Teams zu sein.

Maßnahme: Sprechstunden und Reviews

Damit Entwicklungsteams direkte Unterstützung für wichtige Infrastruktur- und Architekturentscheidungen bekommen, sollen wöchentliche Sprechstunden eingerichtet werden. Diese Sprechstunden sind in erster Linie für dringende Fragen vorgesehen, die innerhalb weniger Tage oder Wochen geklärt werden müssen. Zusätzlich wird das Plattform-Team am gemeinsamen Review-Termin teilnehmen, der ursprünglich für das Vorstellen der Entwicklungsfortschritte gedacht war. Zu diesen Terminen wird das Plattform-Team nun ebenfalls eigene Ergebnisse, z. B. neue Lösungskonzepte, Runbooks und Templates vorstellen, an denen es in den vergangenen Wochen gearbeitet hat. Diese beiden Schritte sollen zu mehr Wissensverteilung und Transparenz führen, damit Entwicklungsteams sich nicht mehr alleingelassen fühlen müssen.

Abb. 3: Zusammenspiel der Teams nach Etablierung des Plattform-Teams. © embarc // INNOQ

Maßnahme: Architektur-Dokumentation an einem Ort

Das Plattform-Team hat im Zuge der Dokumentations-Initiative analysiert, wie die Dokumentation der Betriebsplattformen und Infrastrukturoptionen verbessert werden kann. Dabei haben sie erneut die Ergebnisse des Painstormings herangezogen. Am häufigsten wurde genannt, dass die vorhandene Dokumentation stark fragmentiert, veraltet und schwer auffindbar sei. Diese Eigenschaften treffen allerdings nicht nur auf Infrastruktur-Dokumentation zu, die das Betriebs-Team bereitstellt.

Neue Architekturentscheidungen müssen auf der Grundlage vieler Faktoren getroffen werden. Hierzu zählen Produktanforderungen, Leitlinien und rechtliche Vorgaben sowie Informationen zu den Infrastruktur- und Service-Angeboten der Betriebsplattformen.

Tabelle 1: Für die Teams im Fallbeispiel relevante Dokumentation für den konzeptionellen und betrieblichen Lösungsentwurf (Ausgangssituation)

Dokument	Verantwortlich	Ursprünglicher Speicherort
Produktanforderungen (z. B. auch Qualitätsszenarien)	Produktentwicklung	Wiki
Technologieleitlinien	Enterprise Architektur, CTO	PDFs im Filesharing
Rechtliche Vorgaben	Legal, Datenschutzbeauftragte	PDFs im Filesharing
Infrastruktur- und Service-Angebot der Betriebsplattformen	Betriebs-Team	PDFs im Filesharing
Infrastructure-as-Code-Templates	Betriebs-Team	Infrastruktur-Code-Repository (Modules Ordner)
Anleitungen zum Anbinden von Anwendungs-Infrastruktur (z. B. Auth, Monitoring, Messaging)	Betriebs-Team	Code-Repositorys der Infrastruktur-Komponenten (Readme)
Troubleshooting-Anleitungen und Runbooks	Betriebs-Team	- Wiki - Infrastruktur-Code Repository - Code-Repositorys der Infrastruktur-Komponenten
Anwendungs- und Service-Dokumentation	Entwicklungsteam	- Code-Repositorys (Readme) - Wiki

Es erscheint sinnvoll, die Infrastruktur- und Betriebsdokumentation nicht isoliert zu betrachten. Daher sollen zukünftig alle für die Anwendungsentwicklung relevanten Dokumente – nach dem Vorbild der Produktentwicklung – im Wiki abgelegt oder zumindest verlinkt werden. Dies bedeutet jedoch, dass die Infrastructure-as-Code-Templates des Betriebs-Teams weiterhin im Infrastruktur-Repository verbleiben, da sie in ihrer Natur als "Code" gelten. Allerdings soll eine prägnante Anleitung zur Nutzung und zu den entsprechenden Use-Cases im Wiki auffindbar sein. Auf diese Weise wird das Unternehmens-Wiki zur zentralen Wissensquelle, auch für technische Abteilungen, die von einer verbesserten Auffindbarkeit und Übersichtlichkeit profitieren.

Die Entscheidung für das Wiki als zentralem Dokumentationsort wurde nicht leichtfertig getroffen und stellt vielmehr einen Kompromiss dar. Gerade der Betrieb und die Entwicklung verwenden häufig Markdown-Dokumente, die in Code-Repositorys gespeichert sind. Dies erschwert jedoch die Auffindbarkeit durch die starke Verteilung der Dokumente. Man hat sich deshalb darauf geeinigt, dass auch die Verlinkung externer Dokumentationsorte im Wiki erlaubt ist.

Schnell zeigt sich jedoch, dass alle Beteiligten Schwierigkeiten haben, den passenden Detaillierungsgrad für ihre Dokumentation zu finden. Sollten beispielsweise Runbooks und Troubleshooting-Anleitungen ebenfalls im Wiki hinterlegt werden? Muss die Team-interne Dokumentation so aufbereitet sein, dass auch andere Teams davon profitieren? Diese Unsicherheiten bremsen die Dokumentations-Initiative. Es bedarf daher eines klaren Modells oder einer geeigneten Struktur, um eine effiziente und zielgerichtete Dokumentation zu ermöglichen.

Maßnahme: arc42 als Impulsgeber für die Inhalte

Im Kontext der Dokumentation von Softwaresystemen hat sich arc42 als Vorschlag zur Gliederung von Architekturbeschreibungen über die Jahre als De-facto-Standard im deutschsprachigen Raum etabliert [2]. Im Rahmen der Dokumentations-Initiative bei der MakeItSure soll es nun auch zum Einsatz kommen. arc42 schlägt zur Beschreibung einer Software-Architektur insgesamt 12 Abschnitte vor (s. Abb. 4). Diese beinhalten architekturrelevante Anforderungen, die Modularisierung, Technologieentscheidungen und zu einem gewissen Grad auch die Bewertung der Software im Hinblick auf Risiken und technische Schulden.

Was viele nicht wissen: Auch Infrastrukturaspekte finden in arc42 ihren Platz. Abb. 4 zeigt neben der Gliederung auch, an welchen Stellen der Architektur-Dokumentation wichtige Infrastrukturthemen zu finden sind.

Abb. 4: Infrastruktur-Aspekte in der arc42-Gliederung. © embarc // INNOQ

So sind insbesondere die Qualitätsziele, in Abschnitt 1.2 von arc42, für den Abwägungsprozess von Infrastrukturentscheidungen relevant. Die Verwendung eines zentralen Monitoringsystems könnte demnach auf mehrere Anforderungen einzahlen, wie Zuverlässigkeit, Verfügbarkeit und Sicherheit. Die Qualitätsanforderungen (Abschnitt 10) konkretisieren die Qualitätsziele dann in Form von Szenarien.

Für viele Vorhaben ist ein großer Teil der Infrastruktur vorgegeben. Im Abschnitt 2 – Rahmenbedingungen – werden diese nicht änderbaren Vorgaben und Einschränkungen festgehalten. So könnte unter anderem der Einsatz einer bestimmten Datenbank eine Rahmenbedingung sein, zum Beispiel aus Lizenzgründen. Dennoch könnte Entwicklungsteams in vielen Bereichen ein gewisser Spielraum gegeben werden. So können in den Rahmenbedingungen auch Technologien und Cloud-Services festgehalten werden, aus denen Teams auswählen können.

Für das Festhalten von Architekturentscheidungen sieht arc42 Abschnitt 9 vor. Hier finden die Gründe und Konsequenzen einer getroffenen Entscheidung ihren Platz, wie die Nutzung eines zentralen Monitoringsystems, trotz der Verteilung der Services auf mehrere Betriebsplattformen.
arc42 ist primär zur Beschreibung der Architektur einer einzelnen Anwendung gedacht. CoverFlex von MakeItSure ist dagegen eine stark verteilte Anwendung, die aus vielen Services besteht. Ein umfassendes arc42-Dokument wäre zu groß und zu komplex, da zu viele Teams die für sie relevanten Inhalte beisteuern würden.

Wie also kann arc42 angewendet werden, wenn verschiedene Teams parallel an unterschiedlichen Services arbeiten? Ist jede "Baustelle" eine eigenständige arc42-Dokumentation?

Maßnahme: arc42 auf verschiedenen Ebenen

Um den nötigen Umfang der Dokumentation zu bewältigen, teilen die Teams die Dokumentation in mehrere Ebenen auf. Statt ein großes arc42-Dokument für die gesamte Anwendung zu erstellen, modularisieren sie die Dokumentation. Die Anwendungsdokumentation bildet dabei die makroarchitekturelle Basis und enthält unter anderem alle zentralen Entscheidungen, wie beispielsweise die Vorgabe der Technologien und Protokolle für die Inter-Service-Kommunikation. Diese Anwendungsdokumentation wird maßgeblich durch die Architektur-Community gepflegt, die sich aus den Lead-Developern der Entwicklungsteams zusammensetzt. Dagegen ist jedes Entwicklungsteam für die eigene Service- bzw. Moduldokumentation gemeinschaftlich verantwortlich (s. Abb. 5).

Diese Service-Dokumentation kann sich ebenfalls an der arc42-Gliederung orientieren, bleibt jedoch schlank und fokussiert sich auf die wesentlichen Aspekte des jeweiligen Services. Auch eine steckbriefartige Beschreibung wäre ausreichend. Obwohl arc42 als Template eine umfassende Gliederung für alle Aspekte eines Software-Projekts bereithält, müssen nicht alle Inhalte "ausgefüllt" werden. Das primäre Ziel ist nicht Vollständigkeit, sondern Nützlichkeit. Bei der Bewertung von Nützlichkeit kann es helfen, sich und anderen die Frage zu stellen "Wer hat Interesse daran?" oder "Hätte in der Vergangenheit die Verschriftlichung dieses Aspekts bereits Fragen beantwortet?"

Zusätzlich soll es eine Plattform-Dokumentation geben, die querschnittliche Lösungskonzepte wie Monitoring, zentrale Authentifizierungssysteme oder Routing beschreibt, die wiederum auf Grundlage der Makro-Architekturentscheidungen basieren, die in der Anwendungsdokumentation abgelegt sind. Die konkreten Lösungskonzepte durch die Plattform werden also einfach durch die Anwendungsdokumentation verlinkt. So vermeidet das Plattform-Team Redundanz, die sonst zu Inkonsistenzen der Lösungskonzepte führen würde. Zumal die MakeItSure weitere Produkte auf Basis der Plattform baut.

Abb. 5: arc42 auf verschiedenen Ebenen. © embarc // INNOQ

Die Entwicklungsteams sind sich regelmäßig unsicher, welche Lösungen es in der Infrastruktur gibt und wann oder wie genau sie diese am besten verwenden. Am liebsten kopieren sie Ansätze und Konfigurationen daher aus bestehenden Lösungsteilen, ohne diese wirklich zu verstehen.

Um Entwicklungsteams besser bei ihren Infrastruktur-Entscheidungen zu unterstützen, ergänzen Referenzarchitekturen und Best Practices die Plattform-Dokumentation. Für jede Infrastruktur-Komponente soll es Handlungsanweisungen geben, die im Wiki hinterlegt und durch das Plattform-Team gepflegt werden. Diese ermöglichen es den Teams, auf bewährte Standards zurückzugreifen, während sie gleichzeitig Flexibilität in ihren Architekturentscheidungen behalten.

Maßnahme: Pointierte und zielgerichtete Konzepte

Wie schreibt man nun ein gutes Konzept und gute Handlungsanweisungen? Entscheidend ist neben der grundsätzlichen Struktur und der Zielgruppenorientierung hauptsächlich der Charakter des Konzeptes. Um welche Art von Dokument soll es sich handeln? Hier hilft die Taxonomie des Diátaxis-Frameworks weiter. Diátaxis geht auf Daniele Procida zurück und stellt einen systematischen Ansatz für technische Dokumentation dar [3]. Dabei bezieht er sich nicht wie arc42 nur auf Software-Architektur. Nicht einmal nur auf Software.

Abb. 6: Taxonomie technischer Dokumentation im Diátaxis-Framework nach. © embarc // INNOQ

Diátaxis identifiziert Bedürfnisse unterschiedlicher Zielgruppen, schlägt passende Formen der Dokumentation vor und ordnet diese in Quadranten ein. Abb. 6 stellt diese Kategorisierung in einer Art Kompass dar. Die Idee: sich beim Verfassen eines Konzeptes überlegen, in welche Kategorie es fällt. Und dann nicht mischen, sondern eher verweisen und bei Bedarf ein weiteres mit anderem Charakter anfertigen. Beispiel: Es gibt ein Tutorial, das die Grundlagen vermittelt. In den How-to-Guides setzt man voraus, dass das Erlernte beherrscht wird.

Das Plattform-Team stellt den Entwicklungsteams die für ihre Arbeit nötigen Informationen in Form von How-to-Guides bereit. Sie integrieren dabei Beispiele und Entscheidungsbäume, z. B. bei der Implementierung von Health-Checks für verschiedene Anwendungsplattformen und Anwendungstypen, von der langlebigen Webanwendung bis zum Batch-Job für die Verarbeitung großer Datenmengen.

Tutorials und Erörterungen schreiben sie für Standardprodukte und Cloud-Services nicht selbst, sondern sammeln im Wiki Links zu aus ihrer Sicht besonders empfehlenswerten Quellen, z. B. auch Vortragsvideos. Auch Referenzen für Standardlösungen werden verlinkt statt kopiert. Das gilt natürlich nicht für Informationen, über die das Plattform-Team die Hoheit hat, etwa eine Liste der verschiedenen Umgebungen. Auch für wiederkehrende Aufgaben, die das Plattform-Team selbst ausführt, fertigt das Team Runbooks im Sinne von How-to-Guides an.

Doch es stellt sich schnell heraus, dass Fragen, weshalb eine bestimmte Lösung anderen vorgezogen wurde, von den Teams nur mühselig beantwortet werden können. Ihre Entscheidungen werden durchdacht gewesen sein, aber die Nachvollziehbarkeit scheint noch immer zu leiden. Schnell kommt die Frage auf, ob es auch hierfür eine geeignete Dokumentationsstruktur gibt.

Während Konzepte (Abschnitt 8 in arc42) sich eher um die Anwendung von Lösungsideen drehen, kümmert sich die Dokumentation von Architekturentscheidungen primär um Nachvollziehbarkeit ("Warum haben wir das so gemacht?").

Maßnahme: Nachvollziehbare Entscheidungen mit ADRs

Für das Festhalten von Entscheidungen stolpern unsere Teams schnell über das Schlagwort ADR, kurz für "Architecture Decision Records". Wesentlich geprägt wurde der Begriff von Michael Nygard in einem Blog-Beitrag [4]. Ein ADR dokumentiert eine einzelne, signifikante Entscheidung innerhalb eines Vorhabens als Momentaufnahme auf die immer gleiche Art und Weise. Nygards Blogbeitrag beinhaltet auch einen Vorschlag für eine solche Gliederung, s. Tabelle 2. Hierzu gibt es Alternativen, die sich im Detail unterscheiden, die Kernidee ist aber überall gleich.

Tabelle 2: Abschnitte in einem ADR auf Grundlage von M. Nygard

Abschnitt	Inhalt	Beispiel (Darstellung verkürzt)
Titel (title)	kurze, den Inhalt des ADR wiedergebende Beschreibung der Entscheidung	Zentrales Monitoring
Kontext (context)	Beschreibung der Bedingungen, die zu der Entscheidung geführt haben	Wir betreiben unsere Anwendung verteilt in verschiedenen Umgebungen (On-Premises und Public Cloud). Monitoring mit unterschiedlichen Lösungen erhöht den Aufwand des Betriebsteams und erschwert das Etablieren von einheitlichen Standards
Entscheidung (decision)	Beschreibung der Entscheidung, die im Rahmen des vorher beschriebenen Kontexts erfolgt ist	Wir bauen ein zentrales Monitoring On-Premises auf. Dieses erleichtert zusätzlich die Implementierung von Datensicherheitsbedürfnissen und führt zu einer besseren UX von Entwicklungsteams. Metriken, die wir separat für unterschiedliche Mandanten erheben, trennen wir über geeignete Tags.
Status (status)	Position im Lebenszyklus der Entscheidung wie "proposed", "accepted", "discarded", "deprecated" oder "superseded"	accepted
Konsequenzen (consequences)	Auflistung aller positiven und negativen Konsequenzen	Relevante Metriken von Services, die in der Public Cloud laufen, holen wir über einen passenden Exporter.

Die Teams einigen sich darauf, alle ihre jeweiligen signifikanten Entscheidungen in Form eines ADRs festzuhalten – für sich selbst, aber auch für interessierte Außenstehende, zum Beispiel aus anderen Teams. Die "Signifikanz" machen sie dabei an folgenden Kriterien fest:

Die Entscheidung betrifft nicht nur das eigene Team oder sogar viele Teams.
Die Entscheidung wäre im weiteren Verlauf des Vorhabens schwierig und/oder teuer zu revidieren.
Die Entscheidung hat Einfluss auf den Erfolg unseres Vorhabens, zum Beispiel auf das Erreichen wesentlicher Qualitätsziele.
Die Entscheidung weicht von unseren üblichen Standards ab.

Je mehr dieser Kriterien eine konkrete Entscheidung erfüllt, umso wichtiger ist ein ADR dazu. Mitunter wird das erst später klar, dann dokumentieren die Teams die Entscheidung nach.

Ganz ähnlich, wie arc42 als Struktur auf verschiedenen Ebenen unserer Teams zum Tragen kommt, tun es auch die ADRs, die in arc42 im Abschnitt "Entwurfsentscheidungen" ihren Platz finden. Viel wichtiger als die Gliederung ist aber das Mindset in allen Teams: Wichtige, weitreichende, risikoreiche (kurz signifikante) Entscheidungen halten wir nachvollziehbar fest. Für uns selbst im Sinne eines späteren Ichs, aber auch für Außenstehende, die sich fragen: "Warum habt Ihr das denn so gemacht?". Das können auch neue Teammitglieder sein.

Maßnahme: Prägnante Architekturüberblicke für Plattform und Produkt

Durch die Dokumentations-Initiative produzieren die Teams bei MakeItSure kleinteilige, zielgerichtete Informationsschnipsel. Die ADRs machen die Entscheidungen nachvollziehbar, Konzepte sowie die How-to-Guides und Runbooks kommunizieren Erfahrungswissen und geben so Sicherheit im Tun.

Neue Teammitglieder geben hierzu positives Feedback, berichten aber gleichzeitig über eine gewisse Informationsflut, mit der sie sich konfrontiert sehen. Der Überblick fehlt, zumal die Entwicklungsteams von der Plattform-Dokumentation nur einen geringen Teil für ihre tägliche Arbeit benötigen. Sie interessieren sich vorwiegend für die How-to-Guides. Im ersten Schritt fertigen das Plattform-Team und die Entwicklungsteams Einstiegsseiten im Wiki “Onboarding” an und verlinken dort die wichtigsten Inhalte für den Einstieg. Gleichwohl merken die Teams beim Onboarding, dass es hilfreich wäre, etwas Pointiertes an der Hand zu haben, was das Wichtigste auf einen Blick zeigt. Eine Art "Big Picture".

Im Rahmen einer Sprechstunde entscheiden das Betriebs-Team und die Entwicklungsteams daher, knackige Überblicke sowohl für die Plattform als auch für das Produkt CoverFlex anzufertigen. Sie bedienen sich dabei der bestehenden Inhalte und verdichten diese. Als Form wählen sie jeweils eine Präsentation und beschränken sich im Umfang jeweils auf 12 inhaltliche Folien. Als Struktur legen sie die Abschnitte in Tabelle 3 fest.

Tabelle 3: Struktur eines Folienvortrages für einen Architekturüberblick

Abschnitt	Inhalte	Beantwortete Fragen
Aufgabenstellung	Mission Statement und Kontextabgrenzung (2-3 Folien)	Was leistet die Lösung? Und was nicht?
Einflüsse	Top-Qualitätsziele und wichtige Rahmenbedingungen (2-3 Folien)	Was leitet uns beim Entwurf? Woran müssen wir uns halten?
Lösungsstrategie	Entscheidende Lösungsansätze, zugeordnet zu den Qualitätszielen (Tabelle) und ein informelles Überblicksbild ("Big Picture") (3-4 Folien	Wie sieht die Lösung grundsätzlich aus? Was sind die Eckpfeiler, um die Ziele zu adressieren?
Weitere Informationen	Reflektion und Ausblick auf nächste Schritte, Links auf weiterführende Informationen (2-4 Folien)	Wie geht es weiter?

Das Anfertigen solcher Überblicke als Folienvorträge stellt einen Kompromiss dar. Einzelne Informationen liegen neben dem Wiki nun redundant vor und drohen zu veralten oder auseinanderzulaufen. Die Teams einigen sich daher auf folgende Prinzipien:

Wir konzentrieren uns in den Überblicken auf das Wesentliche.
Die Folien zeigen den Ist-Zustand.
Jede/r in den Teams versteht die Inhalte beider Überblicke und kann die Folien Außenstehenden präsentieren.
Wir nutzen die Folien bei jedem Onboarding und aktualisieren danach (falls nötig).

Ein schönes Beispiel für einen informellen Überblick nach dem Schema von Tabelle 3 findet sich als Folienvortrag und Flyer (PDF, DIN-A3) am Ende dieses Beitrags [5].

Zusammenfassung und Fazit

Mit den geschilderten Maßnahmen konnten die Teams bei MakeItSure die gefundenen Probleme aus dem Painstorming adressieren und Schritt für Schritt Verbesserungen am Entwicklungsprozess erzielen. Tabelle 4 zeigt sie noch einmal im Überblick. Tatsächlich sind sie weder alternativlos noch lösen sich damit alle Probleme in Luft auf. Wir haben daher in der Tabelle auch alternative Ansätze und mitunter passende Ergänzungen mit aufgenommen.

Tabelle 4: Ergriffene Maßnahmen bei MakeItSure im Überblick

Name der Maßnahme	Kurzbeschreibung	Alternative Ansätze oder Ergänzungen
Gründung eines virtuellen Plattform-Teams	Gründung einer unterstützenden Teamstruktur für die Entwicklung, mit dem Ziel der Entlastung bei Betriebsaufgaben.	Die Aufgaben des Plattform-Teams, insbesondere die Begleitung der folgenden Maßnahmen, können auch eine temporäre Initiative oder das Betriebs-Team übernehmen.
Architekturdokumentation an einem Ort	Wir legen alle für den Lösungsentwurf relevanten Informationen so ab, dass sie leicht auffindbar sind. Ein gemeinsames Wiki dient dabei als Einstiegspunkt.	Ein Developer-Portal, z. B. realisiert mit Backstage, kann ebenfalls die Rolle des Einstiegspunktes übernehmen [6].
arc42 als Impulsgeber für die Inhalte	Wir orientieren uns in der Benennung und Strukturierung der Inhalte unserer Architekturdokumentation an der arc42-Gliederung.	arc42 ist im deutschsprachigen Raum sehr verbreitet. Eine interessante Alternative stellen die Arbeiten von Simon Brown dar [7].
arc42 auf verschiedenen Ebenen	Wir arbeiten kleinteilig und setzen nicht ein großes, allumfassendes arc42 ein, sondern wenden es auf unterschiedlichen Ebenen an.	Ein einzelnes Mega-arc42 ist keine Alternative. Man kann auf unterschiedlichen Ebenen jedoch unterschiedliche Gliederungen nutzen, z. B. sehr kompakte Steckbriefe für Services.
Pointierte und zielgerichtete Konzepte	Wir vermitteln unser Erfahrungswissen durch praxistaugliche Anleitungen.	Als grobe Gliederung eines einzelnen Konzeptes bietet sich das 4-Quadrantenmodell (im Englischen auch als 4MAT bekannt) an [8].
Nachvollziehbare Entscheidungen mit ADRs	Wir halten wichtige Entscheidungen in stets gleicher Struktur fest. Alle Teams nutzen dieselbe Vorlage.	Andere Vorschläge zur Gliederung von ADRs als Inspiration [9;10].
Prägnante Architekturüberblicke für Plattform und Produkt	Wir fertigen kompakte Einstiege in Plattform und Hauptprodukt als Folienvortrag an und verweisen für Details auf die entsprechende Dokumentation.	Alternativ zu Foliensätzen reichen ggf. auch Kurzzusammenfassungen als Bestandteil der Dokumentation selbst aus. Im gleichen Medium ist die Aktualität leichter zu gewährleisten.

Dokumentation allein ist kein Selbstzweck. Gut gemacht unterstützt sie im Idealfall in der Kommunikation und gibt Orientierung und Sicherheit in der Frage, was in welcher Tiefe festzuhalten ist. In Vorschlägen gegossenes Erfahrungswissen wie arc42 oder Diátaxis hilft insbesondere auch bei Infrastrukturfragen. Es macht wenig Sinn, das Rad dafür neu zu erfinden.

Quellen