Nicht nur Seiten füllen

Wirklich gute und nützliche Architekturdokumentationen zu schreiben ist einfach schwierig. Es gibt zwar Templates wie arc42, die als guter Startpunkt dienen, aber daraus eine Architekturdokumentation für das eigene Projekt zu machen ist trotzdem eine substantielle Herausforderung. Wir beobachten immer wieder den Ansatz, einfach möglichst schnell alle Kapitel zu füllen, damit mal was da ist und die Pflicht erfüllt ist, ein großer Nutzen für das Projekt entsteht so aber nicht.

Das Ziel muss es ja sein, eine Architekturdokumentation zu erstellen, die den am Projekt beteiligten Stakeholdern hilft, möglichst schnell und effektiv zu verstehen, wie das System funktioniert. Deswegen sollten wir versuchen, nicht nur Seiten zu füllen, sondern die Sachverhalte möglichst gut aufzubereiten.

Dafür geben wir Tipps aus der Praxis und zeigen anhand von konkreten Beispielen, wie man das gut hinbekommt. In diesem Artikel kümmern wir uns um die Kontextabgrenzung.

Was ist eine Kontextabgrenzung?

Nach Klärung der Produktvision und Anforderungen ist die Kontextabgrenzung der erste Schritt im Systemdesign. Das System wird betrachtet als Black Box und verortet in seinem Kontext. Zum Kontext gehören einerseits die Nutzergruppen, die das System verwenden, und andererseits externe Systeme, mit denen unser System interagiert und Daten austauscht. So bietet die Kontextabgrenzung einen ersten Einblick in die Verwendung und Funktionsweise des Systems.

Worauf man bei der Erstellung einer Kontextabgrenzung achten kann, will ich im Folgenden näher diskutieren und anhand eines konkreten Beispiels zeigen. Als Beispiel verwende ich eine Architecture Kata von Neal Ford.

Was sind Architecture Katas?

Softwarearchitekt:innen arbeiten in ihrer Karriere in den allermeisten Fällen an nur einer Handvoll Systemen. Um in einer Sache gut zu werden, muss man diese häufig und kontinuierlich üben. Systemdesign ist hier keine Ausnahme. Architecture Katas sind kleine Aufgaben, anhand derer man Systemdesign üben kann. Man bekommt eine grob beschriebene Problemstellung, meist eine fiktive, aber plausible Geschäftssituation, und soll dafür eine Architektur entwickeln.

Mehr zu Architecture Katas findet ihr in unserem Artikel: Architecture Katas – immer locker in Übung bleiben.

Unser Beispiel

Als Beispiel habe ich die Architecture Kata „I’ll have the BLT“ von Neal Fords Sammlung ausgewählt:

A national sandwich shop wants to enable ‚fax in your order‘ but over the Internet instead (in addition to their current fax-in service)

• Users: thousands, perhaps one day millions
• Requirements:
  • users will place their order, then be given a time to pick up their sandwich and directions to the shop (which must integrate with several external mapping services that include traffic information)
  • if the shop offers a delivery service, dispatch the driver with the sandwich to the user
  • mobile-device accessibility
  • offer national daily promotionals/specials
  • offer local daily promotionals/specials
  • accept payment online or in person/on delivery
• Additional Context:
  • Sandwich shops are franchised, each with a different owner.
  • Parent company has near-future plans to expand overseas.
  • Corporate goal is to hire inexpensive labor to maximize profit.

Der Einfachheit (oder Mangel an Kreativität) halber, nennen wir die Company einfach „BLT Corp.“ und das System „BLT“ .

So sieht es häufig aus

Die folgende Abbildung zeigt ein Beispiel, wie wir es häufig in Architekturdokumentationen antreffen.

Streng genommen erfüllt diese Abbildung mit zugehöriger Tabelle die Definition einer Kontextabgrenzung. Der Informationsgehalt und damit auch der Mehrwert für das Projekt sind aber deutlich eingeschränkt. Unter anderem fehlt es an Detailtiefe, Relationen und Elemente sind unklar, die Tabelle als Erläuterung ist nur wenig detailliert und präzise, etc.

Das muss besser gehen.

So könnte es auch aussehen

Die folgende Abbildung zeigt, wie die Kontextabgrenzung auch aussehen könnte. Anhand dieser will ich einige Tipps und Empfehlungen besprechen, auf die man bei der Erstellung einer Kontextabgrenzung achten kann.

• Ich versuche ein möglichst vollständiges Bild aufzuzeichnen, anhand der Informationen, die gegeben sind. Da, wo Informationen fehlen, können wir auch Annahmen treffen. Diese sollten wir dann aber auch explizit als solche kenntlich machen, damit wir sie bei Bedarf entsprechend ändern können.
• In diesem Beispiel gehe ich eine Stufe mehr ins Detail, indem ich nicht nur einen Block als System zeige, sondern hier auch schon die unterschiedlichen Systemteile auf oberster Ebene. Das heißt, man sieht die unterschiedlichen Apps, die von unterschiedlichen Nutzer:innen verwendet werden, zusammen mit dem Backend und den Interaktionen dazwischen.
• Das Beispiel zeigt die unterschiedlichen Organisationsgrenzen, um Systeme und Nutzer besser zuordnen zu können.
• Es empfiehlt sich anzudeuten, von welchen Organisationen oder Systemen es mehrere oder sogar viele Instanzen gibt (wie beispielsweise von den BLT Stores). Ich habe hier auch gleich Größenordnungen eingefügt, damit man ein Gefühl dafür bekommt, um wie viele Instanzen es sich handeln kann.
• Pfeile
  • Nach Möglichkeit präferiere ich ganz klar Kontrollfluss gegenüber Datenfluss. Kontrollfluss hat den Vorteil, dass man direkt sieht, welches System aktiv die Steuerung übernimmt und wie basierend darauf die Interaktion funktioniert. Da, wo wir noch nicht wissen, wie die Interaktion laufen soll (vielleicht weil wir es noch offen lassen wollen), können wir auch nur den Datenfluss zeigen (siehe beispielsweise bei „faxed orders“).
  • Pfeile haben immer eine eindeutige Richtung.
  • Pfeile sind immer beschriftet.
  • Beim Kontrollfluss sind immer die „Commands“ formuliert.
  • Pfeile sind nach Entitäten und Schreib-/Leseoperationen differenziert.
• Jedes Element trägt einen Stereotyp, damit man direkt erkennt, um was es sich handelt.
• Es gibt eine Legende, die die verwendeten Elemente und Beziehungen beschreibt.
• Ich verzichte auf den Aktor „User“, obwohl es im Text so steht. Das ist zu unpräzise, es handelt sich ja bei allen Nutzergruppen um „User“. Stattdessen verwende ich das genauere „Customer“. Daneben zeige ich alle sonstigen Nutzergruppen, auch solche, die in den Anforderungen nicht explizit genannt sind (wie die Marketing-Mitarbeiter:in).

Natürlich würden wir noch eine schriftliche Erläuterung anfügen, wo wir die Aspekte, die sich aus dem Diagramm nicht direkt ergeben, prägnant beschreiben. Darauf habe ich hier mal verzichtet, um den Artikel kurz zu halten.

Für weitere hands-on Tipps zur Gestaltung von Architekturdiagrammen könnt ihr auch die anderen Artikel auf unserem Blog anschauen, beispielsweise „Wie man einen Pfeil malt“ oder „Wie man Kästchen malt“ .

Fazit

Ich hoffe, die Beispiele helfen Euch als Anhaltspunkte für eure eigenen Kontextabgrenzungen. Mit diesen Tipps seid ihr in der Lage, in einfacher Weise den Detaillierungsgrad zu erhöhen, die Präzision zu verbessern und Mehrdeutigkeiten auszuräumen. So bekommen eure Leser:innen direkt einen besseren Eindruck davon, wie euer System aufgebaut ist und funktioniert. Und damit habt ihr dann auch eine bessere Grundlage für die weiteren Beschreibungen und die weitere Designarbeit.

Also, macht bessere Kontextabgrenzungen!