Dokumentation ist ein Thema in jedem Entwicklungsprojekt. Abhängig vom Vorgehensmodell – agil, iterativ oder ganz klassisch mit Wasserfall – entstehen Lastenhefte, Pflichtenhefte, Studien, Grob- und Fachfeinkonzepte, fachliche und technische Spezifikationen, Entscheidungen, Richtlinien, Anleitungen, Vorgaben, Skizzen, Handbücher, um nur die bekanntesten Artefakte zu nennen, die zum großen Teil unter den Sammelbegriff Projektdokumentation fallen.

Der Begriff Produktdokumentation umfasst verschiedene Dokumente mit produktbezogenen Informationen, die für verschiedene Zwecke gebraucht oder gefordert werden. Die Zielgruppen, für die diese Dokumente erstellt werden, sind so unterschiedlich wie die Ziele, die mit der Dokumentation erreicht werden sollen.

CARDS+ unterstützt eine agile Projektorganisation, Wissensmanagement in einem Entwicklungsprojekt richtig zu organisieren, indem sie zielgerichtet und inkrementell Dokumentation entwickelt. Für Stakeholder und Projektmitarbeiter.

Durch Fluktuation oder durch Änderungen in der Organisation des Unternehmens entsteht ein regelmäßiger Wechsel bei den Projektmitarbeitern und bei allen anderen interessierten Parteien. Damit verbunden ist immer die Gefahr des Verlustes von Wissen. Der Verlust von Wissen in Entwicklungsprojekten ist gefährlich. Die Produktvision geht verloren. Qualität und Produktivität sinkt. Anpassungen und Erweiterungen der Software werden schwieriger. Analysten ist nicht klar, was die Software jetzt schon leistet. Entwicklerteams sind weniger motiviert, da sie in altem Code wühlen müssen, um zu verstehen, wie die Software “tickt”. Ihre Innovationskraft sinkt.

Was beschreibt der Baustein Topic?

Anforderungen an ein System entstehen in den Fachabteilungen aus einem Bedarf, den die Nutzer des Systems haben oder aufgrund von Anpassung an eine veränderte Unternehmensstrategie oder Organisationsstruktur im Unternehmen. Fachabteilung arbeiten innerhalb der Grenzen von Geschäftsbereichen. Anforderungen können daher eindeutig Geschäftsprozessen zugeordnet werden. Konkrete Aufgabenbereiche können wir in den meisten Fällen bereits beim Start des Projektes identifizieren.

Ein Topic ist das Ergebnis von Entscheidungen im Projekt-Management.

Wissen wird nicht vollständig auf einmal vermittelt, sondern wird in einem Prozess erarbeitet. Darum ist es wichtig, einen groben Rahmen zu kennen, an dem wir entscheiden können, dass eine Anforderung überhaupt zum System passt.

In der Methode CARDS+ untersuchen wir jede Anforderung vom Groben (als Epic) ins Feine (als Case). Über den beiden schwebt noch die Zuordnung zum Aufgabenbereich (als Topic).

Motivation

Der Baustein Topic definiert einen klar abgegrenzten Arbeitsbereich im Projekt.

ktip In der Analyse können wir die bewährten Strategien des Requiremments Engineering anwenden. Ein agiles Vorgehen ist für die Erstellung und Pflege eines Topics nicht notwendig.

Jede Anforderung an das Projekt muss der Product-Owner zusammen mit den Stakeholdern eindeutig einem Topic zuordnen. Das sollte in den meisten Fällen problemlos gelingen und stellt für sich einen ersten Schritt der Validierung der Anforderung dar. Eine erfolgreiche Zuordnung bedeutet, dass die Anforderung in diesem Projekt umgesetzt werden kann, ungeachtet anderer Randbedingungen wie Zeit und Geld.

Kann eine Anforderung nicht eindeutig einem bereits vorhandenen Topic zugeordnet werden, dann hat der Product-Owner die Aufgabe, die Anforderung zu teilen. Die neu entstandenen Anforderungen können dann eindeutig einem Topic zugeordnet werden. Dadurch hat das Topic bereits einen hohen Wert, weil unklare oder zu große Anforderungen sehr früh erkannt werden.

Eine Anforderung kann auch dazu führen, dass ein neues Topic erstellt wird, wenn kein existierendes Topic passt. In diesem Fall hat der Product-Owner die Aufgabe, mit den Stakeholdern zu verhandeln, ob es ein neues Topic im System gibt. Diese Entscheidung hat naturgemäß weitreichende Auswirkungen auf das Projekt:

  • Neues Wissen muss aufgebaut werden.
  • Eventuell müssen neue technische Lösungen im Vorfeld erarbeitet werden.
  • Die Projektorganisation muss möglicherweise vergrößert werden.

Ganz wesentlich ist hier die Diskussion darüber, ob die Anforderung tatsächlich in diesem System umgesetzt wird oder ob nicht vielleicht doch ein anderes System besser geeignet wäre.

Definition

 

Was beschreibt der Baustein Epic?

Ein Software-Produkt entsteht durch einen konkreten Bedarf (englisch: need) einer Fachabteilung in einem bestimmten Geschäftsfeld. Oft steckt hinter dem Bedarf eine Vision oder Idee, wie ein Problem gelöst oder ein Prozess optimiert werden kann. Die Reduktion von Kosten oder eine Gewinnmaximierung ist in unserer wirtschaftlich geprägten Welt ebenfalls eine große Motivation der Auftraggeber. Der Product-Owner oder ein Business-Analyst hat die Aufgabe, eine Anforderung des Auftraggebers (englisch: requirement) für alle im Projekt “begreifbar” zu machen. Wir kennen unser System und bewerten und beschreiben den konkreten Wunsch eines Stakeholders, “sein” Produkt zu verändern.

Ein Epic ist das Ergebnis der Anforderungsanalyse.

In der Methode CARDS+ untersuchen wir jede Anforderung vom Groben (als Epic) ins Feine (als Case). Über den beiden schwebt noch die Zuordnung zum Aufgabenbereich (als Topic).

Motivation

Durch den Baustein Epic sollen sowohl Stakeholder als auch das cross-funktionale Team einen Überblick (englisch: big picture) über ein bestimmtes fachliches Problem bekommen. Bei der Analyse werden häufig Entscheidungen getroffen, die maßgeblich den Umfang und die Komplexität der fachlichen Lösung beeinflussen. Diese Informationen sind es, die wir erhalten wollen.

Ein Ergebnis bei der Analyse einer Anforderung ist die Abgrenzung zu anderen, geplanten oder bereits umgesetzten Anforderungen. Anforderungen können sich ergänzen, aber auch widersprechen. Es kommt auch vor, dass eine Anforderung bereits umgesetzt ist, also ein Duplikat ist. Diese Konflikte müssen vom Product-Owner zusammen mit den Stakeholdern geklärt werden.

Ein ganz wichtiges Ziel der Methode CARDS+ ist es, die ursprüngliche Vision oder Idee einer Anforderung zu erhalten und sie jedem Projektmitarbeiter zu vermitteln. Dazu wollen wir die Macht der Bildsprache nutzen.

„Ein Bild sagt mehr als tausend Worte“ ist ein Sprichwort und eine Metapher für den Mehrwert von Bildern gegenüber ausschließlichem Text. Es bezieht sich darauf, dass komplizierte Sachverhalte oft mit einem Bild oder einer Darstellung sehr einfach erklärt werden können und ein Bild meist einen stärkeren Eindruck auf den Betrachter ausübt als ein umfangreicher Text (Quelle: wikipedia).

Was in dieser Definition mitschwingt wird aber sehr oft übersehen: Es geht um ein Bild oder eine Darstellung, die komplizierte Sachverhalte einfach erklären. In der Realität der Software-Projekte entsteht aber sehr oft eine Flut unterschiedlichster Bilder und Diagramme. Jeder Stakeholder und Projektmitarbeiter verwendet sein eigene Art der Darstellung. In der Kommunikation zwischen Stakeholder und Projektmitarbeiter geht dadurch viel Information verloren oder wird unterschiedlich interpretiert. So wie ein Bild mehr als tausend Worte sagt kann ein Bild auch dutzende Bedeutungen haben. Denken sie an Handzeichen, die hier und in anderen Teilen der Welt unterschiedliche Bedeutung haben.

Unser Ziel ist es, für jedes Epic eine gemeinsame Sprache mit eindeutigen Begriffen und – wenn möglich – klarer Bildsprache zu entwickeln.

Ein Foto genügt ja schon, um den Film vor dem inneren Auge zu starten. Ich muss hier nur schreiben: »Wo waren Sie, als Mario Götze das 1:0 im Endspiel schoss?«, prompt haben Sie den Moment wieder präsent (Quelle: SZ).

So eine Bildsprache muss von Business-Analysten und Entwicklern gleichermaßen verstanden werden. Nur so können wir im Team zwischen Analyse und Entwicklung eine Brücke schlagen. Eine gute Bildsprache, die von allen Projektmitarbeiter “gesprochen” wird, unterstützt uns, komplizierte Sachverhalte schneller zu klären. Die Qualität der Kommunikation und letztendlich durch Feedback auch die Qualität der Dokumentation wird steigen.

Die Bildsprache kann trainiert werden, wenn sie in Form einer Legende dokumentiert ist. Als sehr positiver Effekt wird so eine Bildsprache gerne in einem Workshop oder Meeting verwendet, um ein neues Problem zu erläutern oder einen komplizierten Sachverhalt zu erklären. Auf einem Flipchart entstehen dann oft die Entwürfe der Darstellungen, die Business-Analysten oder der Product-Owner dann für das Wiki übernehmen. Alle Projektmitarbeiter haben von Anfang an das gleiche “Bild” der Lösung.

Die Verwendung von Personas hat sich als sehr nützlich erwiesen. Die Persona stellt einen Prototyp für eine Gruppe von Nutzern dar, mit konkret ausgeprägten Eigenschaften und einem konkreten Nutzungsverhalten.

In meiner Artikelserie “Dialoge” benutze ich ebenfalls eine Persona, um meinem “Gesprächspartner” im Dialog nicht nur eine Rolle zu geben. Durch die Persona soll der Gesprächspartner auch einen Charakter bekommen. Natürlich ist Name und Biografie frei erfunden und ich benutze Initialen als Abkürzung der Rolle.

Beispiel: Pirmin Ofner (kurz PO), ein Product-Owner

Auch spezielle grafische Darstellungen sind – wenn sie die Stakeholder gut kennen – sind vorteilhaft. Sie helfen ganz wesentlich bei der Klärung von Fragen oder Problemen im Zusammenhang mit der Anforderung.

Im Personen-Nah- und Fernverkehr gibt es die Zeit-Wege-Linien. Mit diesem sehr einfachen, aber speziellen Diagrammtyp lassen sich viele Anwendungsfälle bei Betriebsabläufen sehr einfach darstellen.

Auch die Verwendung von grafischen Sprachen wie UML oder BPMN können wir nur empfehlen. Allerdings sind diese Sprache meist so mächtig, dass es zur Vorbeugung vor Missverständnissen notwendig ist, eine für das Epic spezifische Einschränkung vorzunehmen oder eine eindeutige Interpretation der Elemente vorzugeben.

Fachklassen werden sehr häufig mit einem UML-Klassendiagramm dokumentiert. Auch wenn die Symbole mittlerweile jedem Entwickler bekannt sind, repräsentieren die Symbole die Entscheidung für eine bestimmte technische Lösung! Klassen können zusätzlich noch mit Stereotypen versehen werden, was erst recht der Hinweis auf eine bestimmte Realisierung ist, die dokumentiert werden muss.

Gerade im Zusammenhang mit einer Software-Architektur, die auf Entwurfsmuster wie microservices, SOA, EAI oder EDA setzen, bietet sich der Einsatz maßgeschneiderte Diagramme an.

Apache Camel ermöglicht die Erstellung von Regeln für Routing und Transformationen. Dabei wird definiert, von welcher Quelle Daten abgerufen werden, wie sie zu verarbeiten sind und zu welchen Zielen diese Daten dann weitergeleitet werden. Dieser Baukasten aus unterschiedlichen Entwurfsmustern kann sehr einfach durch Bilder dargestellt werden. Entwickler werden auf der Projektseite motiviert, eine Bildsprache zu verwenden. Hinter jedem Bild steckt eine ganz konkrete Implementierung mit Apache Camel.

Definition

 

Was beschreibt der Baustein Case?

Mit einer Anforderung drückt ein Stakeholder einen aus seiner Sicht wichtigen Bedarf an einer Erweiterung oder Änderung des Software-Produktes aus. In der Analyse der Anforderung wollen Product-Owner, Business-Analysten und das cross-funktionale Team einen Einblick in das fachliche Problem bekommen und ein gemeinsames Verständnis über Ziele und Lösungen entwickeln. Wir machen uns auch Gedanken über die Auswirkungen der Umsetzung. Das Sammeln von relevanten Informationen (das Produktwissen) und das Einholen von Feedback aus den Fachabteilungen ist ein ganz wichtiger Teil der Analyse.

Ein Case ist das Ergebnis von Entscheidungen aus dem Backlog-Management agiler Software-Entwicklung.

In der Methode CARDS+ untersuchen wir jede Anforderung vom Groben (als Epic) ins Feine (als Case). Über den beiden schwebt noch die Zuordnung zum Aufgabenbereich (als Topic).

Motivation

Konkrete Anwendungsfälle, Sonderfälle und bekannte Fehlersituationen beschreiben wir mit dem Baustein Case. Es klingt möglicherweise paradox, aber wir wollen auch einen Case erfassen, für den es keine Lösung gibt. Denn wenn es gute Gründe gibt, einen Case nicht umzusetzen (z.B. zu teuer, tritt einmal im Jahr auf), ist die erfasste Situation trotzdem wichtiges Produktwissen und wert, aufgeschrieben zu werden.

ktip Ein Case darf nicht mit einem Usecase verwechselt werden. Ein Usecase hat unterschiedliche Bedeutungen. Die Praxis reicht von einem Usecase auf sehr hohem Niveau bis auf Ebene von UML-Diagrammen mit dem Ziel, die Software mit Usecases zu beschreiben. Ein Case hat jedoch große Ähnlichkeit mit der Idee der Slices aus der agilen Technik “Use Case 2.0”, das 2011 von  Ivar Jacobson, Ian Spence und Kurt Bittner in dem gleichnamigen eBook veröffentlicht wurde.

Ein Case wird wie eine Story im Product-Backlog in der Sprache der Nutzer geschrieben. Die Techniken und Methoden für die Erstellung einer Story, z.B. die Erzählmethode (englisch: story telling), kann ohne Einschränkungen auch für das Schreiben eines Case verwendet werden. Im Unterscheid zu einer Story hat ein Case keine Akzeptanzkriterien und auch keine weitere Ebene der Verfeinerung durch Aufgaben. Ein Case ist in sich abgeschlossen, testbar und im Normalfall klein genug, um in einem Sprint umgesetzt zu werden. Wie bei einer Story sollten wir bei der Beschreibung eines Case unbedingt das Prinzip INVEST berücksichtigen.

Die fachliche Lösung zeigt im wörtlichen Sinn nur die Essenzschritte, die in der Anwendung zum erforderlichen Ergebnis führt.

Bei der Beschreibung von Lösungen müssen wir ganz stark darauf achten, dass wir nur die “Essenz” der Lösung erfassen..

Die Gefahr ist, in (meist technisch motivierte) Details abzugleiten. Wir müssen in einem Case dem Entwickler nicht erklären, wie er Abläufe und Strukturen im Rahmen der Architektur realisieren soll. Das weiß ein Entwickler in den meisten Fällen besser! Aber auch Entwickler und Tester profitieren von der Beschreibung des Weges, der für den beschriebenen Case in der Software-Architektur notwendig ist. Sie erkennen in den Essenzschritten auf einen Blick betroffene Komponenten, sehen Abhängigkeiten.

Definition

Was beschreibt der Baustein Layout?

Benutzeroberflächen sind das für die Nutzer sichtbare Ergebnis unseres Projektes. Zum einen unterstützt die Benutzeroberfläche Abläufe innerhalb von Geschäftsprozessen des Unternehmens. Auf der anderen Seite stellen die Daten, die mithilfe der Benutzeroberfläche erfasst werden, einen hohen Wert für die Nutzer und das Unternehmen dar. In der Benutzeroberfläche einer Anwendung steckt daher ein enormes Wissen. Dieses Wissen gilt es zu sichern.

In einem Layout beschreiben wir die Gestaltung und die Struktur der Benutzeroberfläche. Layouts benötigen wir bereits vor dem Start des Sprint in der geforderten Qualität. Mit bestimmten Typen von Layouts wird bereits in der Analyse der Versuch unternommen, wiederverwendbare Elemente der Benutzeroberfläche zu identifizieren. Teilbereiche der Benutzeroberfläche erfassen wir als Layouts vom Typ Panel. Der Designer der Benutzeroberfläche gibt dem Entwickler damit frühzeitig den Hinweis, dass es Potential für eine wiederverwendbare Software-Komponente gibt. Weitere Bausteine für eine geplante Wiederverwendung sind Layouts vom Typ Prompt und Widget.

Motivation

Im Zusammenhang mit der Spezifikation von Benutzeroberflächen der Anwendung unterscheiden wir Layouts und Manuals. Beide Artefakte haben das Ziel, die Benutzeroberfläche zu beschreiben.

Beispiel Beschreibung im Layout Beschreibung im Manual
Eingabe eines Wertes Im Layout legen wir fest, dass es ein einzelnes Feld mit freier Eingabe ist. Wir definieren die erlaubten Zeichen und die maximale Anzahl der Zeichen. Im Manual legen wir je Anwendungsfall fest, welche Werte fachlich gültig sind. Wir legen auch fest, dass bei Fehleingaben eine Fehlermeldung angezeigt wird.
Eingabe eines Datums Im Layout beschreiben wir das Datumsformat, ob eine freie Eingabe erlaubt wird und welcher Dialog aufgerufen wird, um eine Datum aus einem Kalender zu wählen. Im Manual legen wir je Anwendungsfall fest, in welchem Bereich das Datum eingegeben wird. Auch Abhängigkeiten zwischen Feldern (z.B. die Grenzen eines Intervalls) erklären wir hier.
Eingabe einer Entscheidung Im Layout legen wir fest, dass wir eine Gruppe von Umschaltern mit einem gemeinsamen Titel verwenden. Im Manual legen wir je Anwendungsfall fest, welche Wahlmöglichkeiten zulässig sind.

Im Grunde genommen muss sich der Analyst beim Schreiben von Layout und Manual eine Frage stellen: Muss das ein Nutzer wissen? Wenn diese Frage mit ja beantwortet wird, gehört diese Information ins Manual. Auf der anderen Seite wird für ein Layout ganz klar und eindeutig festgelegt, was der Analyst beschreiben muss, um das Dokument «ready» für die Entwicklung zu bekommen. Die Zielgruppe für ein Manual ist daher ganz klar der Nutzer, während die Zielgruppe für ein Layout das cross-funktionale Team ist.

Für das Schreiben einer Layout-Seite gibt es ein praxistaugliches agiles Vorgehen:

  1. Vor dem Sprint legen wir ein Layout mit Mockup an. In der Beschreibung vermitteln wir grob den Wert dieser Benutzeroberfläche für den Nutzer.
  2. Im Layout beschreiben wir die Elemente und deren Initialisierung. Die  Validierung beschreiben wir nur dort, wo sie sich nur auf ein Element alleine bezieht.
  3. Wir legen für jeden Anwendungsfall, der durch die Akzeptanzkriterien in der User-Story gefordert wird, ein Manual an und beschreiben dort aus Sicht des Nutzers die besonderen Randbedingungen für die Verwendung der Benutzeroberfläche.
  4. Im Sprint klären wir während der Entwicklung weitere Details und aktualisieren das Layout und die Manuals. Ebenfalls als Teil der Manuals beschreiben wir die feld-übergreifenden Validierungen.

Am Ende des Sprints haben wir mit diesem Vorgehen ein fertiges Layout mit einem Manual je realisiertem und getesteten Anwendungsfall. Die Kombination aus Layout und Manuals ergibt eine vollständige Beschreibung der Struktur und des Verhaltens der Benutzeroberfläche. Aus diesem Ansatz ergeben sich für das cross-funktionale Team eine Reihe von Vorteilen.

  • Wir vermeiden redundante Inhalte.
  • Wir können ein Layout vor dem Start des Sprints in ausreichender Qualität bereitstellen. Während des Sprints sind im Layout nur Fehlerkorrekturen aufgrund des Feedback der Entwickler notwendig.
  • Wir erstellen Manuals als Entwurf des Benutzerhandbuches während des Sprints mit Hilfe der “echten” Anwendung. Entwickler und Tester verwenden die Manuals daher frühzeitig und validieren automatisch die Beschreibungen.
  • Wir können uns bei der Erstellung von Testfällen von Beginn an auf die Manuals beziehen. Manuals haben daher für einen Tester einen hohen Wert.

Am Ende des Sprints haben die Entwickler das Layout der Benutzeroberfläche realisiert und die Tester mit der Erstellung der Testfälle die Manuals dazu fertiggestellt.

Mockup

Entwickler erhalten durch das Mockup die Idee für die Gestaltung der Benutzeroberfläche. Die Aufgabe des Entwicklers ist es, diese Idee in der gegebenen Architektur und unter Berücksichtigung des aktuell gültigen Style-Guides umzusetzen. Durch die Verwendung von Mockups sind wir im Projekt in der Lage, ein Layout als Ganzes darzustellen, ohne Gefahr zu laufen, dass in der Zwischenzeit eine Änderung im Style-Guide dazu führt, dass das Layout “verdirbt” und überarbeitet werden muss.

Ein Mockup ist eine realitätsnahe Darstellung der Benutzeroberfläche und vermittelt das look and feel!

Realitätsnah bedeutet in diesem Zusammenhang, dass wir erkennen können, in welcher Architektur wir uns bewegen, ohne aber zu sehr ins Detail zu gehen. Anders gesagt: Ein Screen für eine mobile Anwendung würde sich auf jedem Fall von einem Dialog einer Desktop-Anwendung unterscheiden. Wir machen aber keinen Unterschied, ob wir nun die Desktop-Anwendung mit web-basiert mit JSF oder klassisch mit JavaFX machen. Dadurch behalten die Entwickler eine gewisse Freiheit bei der technischen Umsetzung. Diese Freiheit geht so weit, dass es möglich ist, die technische Umsetzung zu ändern. Ein gutes Beispiel ist der Umstieg von Swing auf JavaFX bei einer Desktop-Anwendung. Ich denke, dass es viele Gründe für diesen Wechsel gibt. Es wäre aber eine große Einschränkung für die Entwicklung, wenn die Benutzeroberfläche in JavaFX exakt gleich ausschauen muss wie die existierende Umsetzung mit Swing.

Auch die Gestaltung und die Farbe der Steuerelemente und Bilder ist nicht endgültig festgelegt und lässt genügend Spielraum, um beispielsweise einen Grafiker während der Entwicklung zu beauftragen, ein durchgängiges Farbschema und gut gestaltet, “coole” Icons zu entwerfen. Gleichzeitig können wir aber den Stakeholdern schnell und ausreichend genau einen Eindruck von der geplanten Benutzeroberfläche vermitteln.

Ein wesentlicher Vorteil eines Mockup gegenüber einem Screenshot ist die Möglichkeit, jede fachliche Situation in der Benutzeroberfläche darstellen zu können. Das gilt auch für Situation, die in der echten Anwendung nur mit sehr großem Aufwand herzustellen ist oder nur kurze Zeit existiert.

Definition

Was beschreibt der Baustein Manual?

Das Benutzerhandbuch ist das “Buch”, in dem die Bedienung der Software für die Nutzer beschrieben ist. Es ist Teil der Produktdokumentation. Projekte planen die Aktualisierung des Benutzerhandbuches gerne so spät wie möglich. In Projekten mit klassischen Vorgehensmodell  (“Wasserfall”) ist sowas noch einigermaßen gut planbar. Mit den agilen Methoden in den Projekten ergibt sich das Problem, dass am Ende des Sprints auch das Benutzerhandbuch fertig sein muss. Das ist meiner Ansicht nach nur schwer leistbar, weil der Großteil der Arbeit in der Gestaltung des Inhaltes liegt – fehlerfreie Inhalte vorausgesetzt. Oft ist die Gestaltung des Benutzerhandbuches und die Art der Veröffentlichung an Vorgaben des Unternehmens gebunden. Es ist auch schwer vorstellbar, dass jedes cross-funktionale Team die Rolle des technischen Redakteurs besetzen kann, wie es für ein professionelles Handbuch notwendig ist.

Im Zusammenhang mit der Spezifikation von Benutzeroberflächen der Anwendung unterscheiden wir Layouts und Manuals. Beide Artefakte haben das Ziel, die Benutzeroberfläche zu beschreiben.

In einem Manual beschreiben wir die Verwendung der Benutzeroberfläche, also das gewünschte fachliche Verhalten aus Sicht der Nutzer. Manuals sind als ideal geeignet, um daraus Testfälle abzuleiten. Aus diesem Grund werden während der Realisierung einer Benutzeroberfläche – hier verwenden wir die Layouts – für den Test bereits die Manuals erstellt. Wir legen für jeden Anwendungsfall, der durch die Akzeptanzkriterien einer User-Story gefordert wird, ein Manual an und beschreiben dort aus Sicht des Nutzers die besonderen Randbedingungen für die Verwendung der Benutzeroberfläche.

Motivation

Der Aufbau eines Manuals unterscheidet sich wesentlich von einem Layout. Eine einigermaßen komplexe Benutzeroberfläche bietet eine Vielzahl möglicher Anwendungsfälle, die sich durch unterschiedliche Eingaben und Beschränkungen bei der Eingabe unterscheiden. Um die Erfassung dieser Anwendungsfälle effizient zu gestaltet, beschreiben wir jeden Anwendungsfall separat in einem Manual.

Ein Manual kann leicht in das endgültige Benutzerhandbuch übernommen werden. Ein Manual stellt sozusagen den Entwurf des Benutzerhandbuches dar.

Ein Manual können wir sinnvoll und effizient erst fertigstellen, wenn eine erste Version in der Software realisiert wurde. Der Autor eines Manuals benötigt die Möglichkeit, die Anwendungsfälle der Benutzeroberfläche in der Anwendung durchzuführen.

Am Ende des Sprints haben die Entwickler das Layout der Benutzeroberfläche realisiert und die Tester mit der Erstellung der Testfälle die Manuals dazu fertiggestellt.  Manuals werden nur für Layouts vom Typ Client, Window oder Dialog erstellt. Für untergeordnete Layouts vom Typ Panel, Prompt oder Widget erstellen wir keine Manuals. Der Grund ist, das diese Layouts das Ziel der Wiederverwendung unterstützen. Wiederverwendung bedeutet aber, dass die gleiche Software-Komponente in unterschiedlichen Kontexten in der Anwendung genutzt wird. Eine einheitliche Beschreibung im Sinne eines Benutzerhandbuches ist praktisch unmöglich.

Die Kombination aus Layout und Manuals ergibt eine vollständige Beschreibung der Struktur und des Verhaltens der Benutzeroberfläche. Die Manuals sind außerdem ein gut gepflegter Entwurf des Benutzerhandbuches. Gut gepflegt, weil die Manuals während des Sprints erstellt und verwendet wurden und damit Fehler durch das Feedback der Tester weitestgehend gefunden und beseitigt wurden.

Die Erstellung des Benutzerhandbuches am Ende des Releases wird dadurch stark vereinfacht und auf redaktionelle Arbeiten (z.B. die rechtschreibliche, stilistische, grammatikalische und inhaltliche Verbesserung der Texte) und die optische Gestaltung reduziert. Die Inhalte sind ja bereits als Fragmente in Form der Manuals vorhanden. Ein ganz klares Plus für die Qualität des Benutzerhandbuches.

Zur Illustration des Textes in einem Manual verwenden wir ausschließlich Screenshots aus der Anwendung. Wir gehen hier bewusst das Risiko ein, dass sich das Mockup im Layout und der Screenshot im Manual unterscheiden. Abweichungen stellen immer irgendeine Art von Fehler dar.

  • Ist es eine falsche Realisierung des Layouts durch den Entwickler, dann erstellen wir einen Defekt zur Korrektur der Software.
  • Eine fehlerhaftes Mockup kann durch nachträgliche Änderungen während der Realisierung entstehen, wenn das Feedback des Entwicklers nicht eingearbeitet wurde.

Definition

 

Was beschreibt der Baustein Decision?

In unserer schnelllebigen Zeit, wo technische Lösungen in kurzer Zeit entstehen und nach wenigen Jahren durch noch bessere Lösungen ersetzt werden, ist es besonders wichtig, die Gründe für die Wahl einer Technologie zu kennen. Streaming-Technologien wie Storm oder Spark bekommen gerade Konkurrenz durch das aufstrebende Flink. Auch im Bereich der No-Sql-Datenbanken gibt es mit HBase, Cassandra, Redis, PostgreSQL, MongoDB und CouchDB eine Vielzahl von Optionen. Und wer kann heute schon sagen, ob nicht auch die Konzepte des “machine learning” nicht bald zum Standardbaukasten einer modernen cloud-basierten Software-Architektur gehören.

Motivation

Software-Architektur entsteht immer, unabhängig davon, ob wir sie bewusst entwickeln oder ob wir sie einfach “passieren” lassen. Wichtig ist, dass das Vorgehen zum Projekt und zum Team passt und vom Auftraggeber akzeptiert wird. Die natürliche Tendenz der meisten Menschen ist, die Architektur zu planen. Aus dieser Motivation heraus entstehen sehr schnell Schichtenmodelle oder Baupläne für Komponenten, die die Struktur der Software beschreiben. Ich halte es aber viel wichtiger, dass die Entscheidungen dokumentiert werden, die zu solchen Strukturen führen. Ich bin überzeugt, dass wir mit den Mitteln der Entwickler wie git-Repositories, Namensräumen und objekt-orientierter Programmierung sehr viele gute Möglichkeiten haben, die Struktur einer Software “lesbar” zu machen. Entscheidungen können wir jedoch kaum oder nur schwer aus dem Code ablesen. Das Wissen über alternative Lösungen ist aber auf jeden Fall verloren, wenn die sie nicht dokumentiert werden.

Unter dem Titel “Knigge für Software-Architekten” haben Peter Hruschka und Gernot Starke einen lesenswerten Artikel über Entscheider geschrieben.  Obwohl der Artikel bereits im Jahr 2012 geschrieben wurde, hat er meiner Ansicht nach nichts an Aktualität verloren. Ich bin überzeugt, dass gerade in agilen Projekten die Transparenz bei Entscheidungen wichtiger ist als eine umfassende Dokumentation der Struktur einer Software. In Scrum wird die Software-Architektur von Sprint zu Sprint kontinuierlich weiterentwickelt. Software-Experten im Team treffen wichtige Entscheidungen im Idealfall termingerecht, also nicht zu früh, aber auch nicht zu spät (englisch: last responsible moment).

ktip Über diesen Zeitpunkt des “last responsible moment” gibt es ungezählte Blog-Beiträge und Diskussionen, jedes ernstzunehmende Buch über Software-Architektur widmet sich diesen Thema. Die Methode CARDS+ beschäftigt sich nicht mit der Frage, wann der beste Zeitpunkt für eine Entscheidung ist. Auch auf die Frage, wer die Entscheider sind, wird CARDS+ keine Antwort geben.

Mit dem Baustein Decision gibt es eine einfache Möglichkeit, eine Entscheidung genau dann zu dokumentieren, wenn sie getroffen wird. Zu diesem Zeitpunkt hat sich das cross-funktionale Team mit dem Thema beschäftigt, kennt neben der favorisierten Lösung noch weitere Alternativen. Jetzt ist jeder im Team in der Lage, Feedback zur Lösung und zur Begründung der Entscheidung zu geben. Jede Decision ist außerdem eine Sicherung von wertvollem Wissen der Software-Experten. Dadurch wird das Projekt robust gegenüber Fluktuation der Mitarbeiter.

Ein Punkt ist jedoch ganz wichtig. Dokumentierte Entscheidungen müssen von den Teams berücksichtigt werden. Sie sind Vorgaben, die einzuhalten sind. Natürlich heißt das nicht, dass eine einmal getroffene Entscheidung nie mehr korrigiert wird. Ganz im Gegenteil. Gerade wenn die Entwickler feststellen, dass eine Entscheidung Probleme verursacht, sollte das Team über Alternativen nachdenken. Aber hier kommt der Vorteil zum Tragen, dass wir die schon einmal betrachteten Alternativen kennen.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben definieren und Vorlagen zur Verfügung stellen.

Die ganz wichtigen Entscheidungen werden als “Architecture Principles” beschrieben. Mit einem “Statement” beschreibt man die Essenz der Entscheidung, in einem “Rational” erklärt man die Auswirkungen der Entscheidung und die “Implications” definieren die Anforderungen an Projekt und Produkt bei der Umsetzung der Entscheidung. Zusätzlich gibt es das “Decision Log” als Teil des “Governance Log” zur Sicherung von Entscheidungen im Verlauf des Projektes.

Quelle: TOGAF9 online documentation

Hier ist es wünschenswert, alle wichtigen Entwurfsentscheidungen geschlossen nachlesen zu können. Wir werden aber aufgefordert abzuwägen, inwiefern Entwurfsentscheidungen zentral dokumentiert werden sollen oder wo eine lokale Beschreibung (z.B in der Beschreibung von Bausteinen) sinnvoller ist.

Quelle: ARC42 online documentation

Definition

 

Was beschreibt der Baustein Domain?

Software hat immer eine Struktur, unabhängig vom Architekturstil. Sind es bei monolithischen Systemen noch Schichten und Module, reden wir bei service- oder nachrichten-orientierten Systemen ganz allgemein von Diensten. Ein Dienst hat öffentliche Schnittstellen und eine Aufgabe. Schichten und Module werden zu Details der Implementierung eines Dienstes. Beim Domain-Driven Design (kurz DDD) nutzen wir den Begriff Module, um Ordnung und Übersichtlichkeit in ein Modell zu bringen. Ein weiterer Treiber für eine Struktur ist die Verwaltung von Code. Wir organisieren Code in Build-Projekten (z.B. mit gradle oder maven) und speichern Versionen davon in einem Code-Repository (z.B. git).

Kurz gesagt, es gibt eine ganze Reihe von Konzepten und Ansätzen, mit der wir eine Software strukturieren können. Ziel ist immer, die Komplexität der Software in den Griff zu bekommen, einen Überblick zu behalten.

Motivation

Mit dem Baustein Domain wollen wir die Struktur der Software beschreiben, weitestgehend unabhängig vom Architekturstil und Programmiersprache. Entwickler nutzen Konzepte der Programmiersprache für Namensräume, um Struktur in den Code zu bringen.

In Java definieren wir mit package einen Namensraum. Ein package ist eine Sammlung von interfaces, classes oder enums. Um Namenskonflikte aufzulösen, wenn es in zwei verschiedenen packages zwei identische Bezeichner gibt, sind sie in einer Hierarchie geordnet.

Java bietet eine weitere Möglichkeit, Code zu einer Einheit zusammenfassen. Die Grundlage bildet eine jar-Datei, die neben class-Dateien und Ressourcen auch Metadaten in Form einer manifest-Datei enthält. Es gibt allerdings auch Probleme bei der Verwendung komplexer classloader-Hierarchien mit war-, ear- und vielen weiteren Varianten von jar-Dateien, die oft als jar hell bezeichnet wird.

In C++ nutzen wir einen namespace, um Code zu einem Namensraum zusammen zu fassen.

In Python schreiben wir Skripte, die Code zu einem Namensraum zusammenfassen. Python nennt sie module. Python kennt auch das Konzept der packages, um ein module weiter zu strukturieren. Um Namenskonflikte aufzulösen, wenn es in zwei verschiedenen packages zwei identische Bezeichner gibt, haben packages eine Hierarchie.

Namensräume müssen wir im Wiki nicht ausführlich dokumentieren. Das wäre redundant. Es gibt außerdem für viele Programmiersprachen ein Werkzeug, das eine von Menschen lesbare Dokumentation aus dem Code erstellen kann. Die Dokumentation kann meist durch spezielle Kommentare im Code angereichert werden. So kann die Struktur von Code für jeden im Projekt sichtbar gemacht werden.

Javadoc ist ein Werkzeug, das aus Java-Code eine Dokumentation erstellt. Als Ausgabeformat unterstützt Javadoc nur HTML, durch doclets können aber weitere Ausgabeformate ergänzt werden.

Doxygen ist ein Werkzeug, das aus Code der Programmiersprachen C++, C, Objective-C, Java, Python, Fortran und IDL eine Dokumentation erstellt. Als Ausgabeformat unterstützt Doxygen z.B. HTML, LaTeX, XML, RTF, PostScript, PDF und Markdown.

CARDS+ bietet eine schöne Möglichkeit, alle für das Verständnis eines Systems notwendigen Bestandteile im Wiki zu erfassen. Mit dem Baustein Service geben wir einem konkreten Dienst einen eindeutigen Namen. Wir nutzen den Baustein Domain, um Dienste zu einer Gruppe in einem Code-Repository zusammenzufassen.

  • Der Name der Domain verwenden wir auch als Bezeichnung für das Code-Repository.
  • In der Beschreibung der Domain erklären wir das Zusammenspiel der Dienste.

Es ist ganz wichtig, dass wir das Wiki als Verzeichnis für Dienste sehen. Es ist eine große Chance, eine konsistentes und nachvollziehbares Schema für Namen durchzusetzen. Das funktioniert natürlich nur, wenn wir die Seiten im Wiki vor dem Start der Entwicklung erstellen und bis zum Abschluss der Implementierung laufend aktualisieren.

Während der Realisierung eines Dienstes treffen Entwickler Entscheidungen, die nur für diese Gruppe von Diensten gilt. Und die dokumentieren wird nicht mit dem Baustein Decision, sondern im Baustein Domain.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben des Architekturentwurfs definieren und Vorlagen für die Dokumentation zur Verfügung stellen.

Zuerst erfasst man ein “Architecture Principle”, welches beispielsweise den Einsatz von Schichten erklärt (das “Statement”) mit seinen Randbedingungen (das “Rationale”) und Auswirkungen (die “Implications”).

Das Kapitel 35 mit dem Titel “Architectural Artifacts” zeigt die unzähligen Möglichkeiten für die Darstellung des Systems (“View”) aus einer bestimmten Perspektive (“Viewpoint”) für einen bestimmten Aspekt der Funktionsweise des Systems (“Concern”).

Quelle: TOGAF9 online documentation

In der Bausteinsicht wird die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Teilsysteme, Klassen, Interfaces, Pakete, Bibliotheken, Frameworks, Schichten, Partitionen, Tiers, Funktionen, Makros, Operationen, Datenstrukturen, …) sowie deren Beziehungen dokumentiert. Abhängig vom Architekturstil nutzen wir den Baustein Domain, um Module, Komponenten oder Schichten zu beschreiben.

Quelle: ARC42 online documentation

Definition

Was beschreibt der Baustein Service?

Lange Zeit haben wir große monolithische Systeme gebaut. Auch wenn der Ruf dieses Architekturstils nicht mehr der Beste ist, funktionieren manche diese Systeme doch seit vielen Jahren und erfüllen ihre Aufgabe zur vollen Zufriedenheit der Nutzer. Mit der Idee eines Microservice hat sich ein neuer Ansatz durchgesetzt. Dieser Architekturstil wird oft als Nachfolger der service-orientierten Architektur (kurz SOA) bezeichnet. Beide Architekturstile führen zu verteilten Systemen. Ein System aus vielen verschiedenen Microservices zusammenzustellen eröffnet vor allem hinsichtlich Robustheit und Skalierbar völlig neue Optionen. Microservices haben den großen Vorteil, dass es mit Technologien wie Spring Boot, Ratpack oder Dropwizard möglich ist, leichtgewichtige Lösungen zu bauen. Im reaktiven Manifest wird ein nachrichten-orientierter Architekturstil definiert, der ideal zu den Technologien aus dem Apache-Universum passt. Verteilte Verarbeitung von Datenströmen quasi in Echtzeit ist mit Storm, Spark oder Flink in Verbindung mit Kafka realisierbar.

Unabhängig vom Architekturstil besteht jedes System aus Diensten. Ein Microservice ist ein ein Dienst. In einem nachrichten-orientierten System mit Storm ist eine Topologie ein Dienst. Aber auch in monolithischen Systemen lassen sich Dienste identifizieren und realisieren.

Motivation

Mit dem Baustein Service wollen wir einen Dienst eines Systems beschreiben, weitestgehend unabhängig vom Architekturstil und der gewählten technischen Lösung. Dabei steht der fachliche Nutzen des Dienstes im Vordergrund. In einem agilen Projekt können wir die Entscheidung für die technische Umsetzung getrost dem cross-funktionalen Team überlassen. Am Ende der Umsetzung eines Dienstes wird der Steckbrief des Dienstes um eine kurze Beschreibung der tatsächlichen gewählten Lösung ergänzt.

Der Baustein Service beinhaltet Entscheidungen für bestimmte Technologien, die für die Umsetzung notwendig sind. Die Verwendung einer Technologie, die große Auswirkungen auf den Betrieb hat oder nur sehr schwer ausgetauscht werden kann, muss immer durch eine Entscheidung mit dem Baustein Decision begründet werden.

Wichtig ist, dass der Baustein Service dafür gedacht ist, einem Dienst eines Systems einen eindeutigen Namen zu geben. Der Name des Service wird auch im Code verwendet und schlägt damit die Brücke zwischen Wiki und Code. Abhängig von der Technologie, mit dem der Dienst realisiert wird, nutzen wir den Namen des Bausteins als Namensraum, als gleichnamige Klasse oder als Prefix für eine Menge von Klassen. Der Name kann aber auch als Bezeichnung einer Konfigurationsdatei verwendet werden.

Die dynamische und statische Sicht im Baustein soll dem Leser beim Navigieren im Code unterstützen. Wir wollen aber nur das dokumentieren, was wir nicht durch lesbaren Code bereits ausreichend dokumentiert haben. Mit Swagger kann beispielsweise ein REST-Service eindeutig beschrieben werden. Eine WSDL beschreibt ein Web-Service. Datentypen beschreiben wir mit einem XML-, AVRO– oder JSON-Schema. Docker nutzen wir, um agile Vorgehensmodelle, allen voran Scrum, und die Idee der DevOps optimal zu unterstützen. In der statischen Sicht beschreiben wir die Konfigurationsmöglichkeiten des Containers.

Code und andere Artefakte der Entwickler in einem Code-Repository sind somit Teil der Dokumentation. Ein Leser der Produktdokumentation wird durch den Baustein Service in die Lage versetzt, den Code für diesen Dienst zu finden und zu verstehen.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben des Architekturentwurfs definieren und Vorlagen für die Dokumentation zur Verfügung stellen.

Das Kapitel 22 mit dem Titel “Using TOGAF to Define & Govern SOAs” beschäftigt sich ausschließlich mit der Frage, was für ein SOA-basiertes System in den verschiedenen Phasen dokumentiert werden kann. Interessant ist der letzte Satz:

When delivering SOA with TOGAF, the practitioner should never lose sight of the final objective: SOA solutions that address managing the enterprise’s complexity and provide business agility.

Der Software-Experte muss am Ende selbst entscheiden, was und wie genau er Elemente eines SOA-basierten Systems dokumentiert.

Quelle: TOGAF9 online documentation

In der Bausteinsicht wird die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Teilsysteme, Klassen, Interfaces, Pakete, Bibliotheken, Frameworks, Schichten, Partitionen, Tiers, Funktionen, Makros, Operationen, Datenstrukturen, …) sowie deren Beziehungen dokumentiert. Dienste werden als Teilsysteme beschrieben. Das Zusammenspiel der Bausteine wird in der Laufzeitsicht beschrieben.

Quelle: ARC42 online documentation

Definition

Was beschreibt der Baustein Event?

Das reaktive Manifest ist der Versuch, die Werte für einen Architekturstil zu definieren, der das Ziel verfolgt, robuste, fehlertolerante und gut skalierbare Systeme zu schaffen. Nachrichten-orientierte Kommunikation zwischen den Diensten ist ein weiteres wichtiges Ziel dieses Architekturstils. Viele dieser Ziele erreichen wir durch die Nutzung moderner Technologien für die Nachrichtenverteilung, z.B. Kafka oder RabbitMQ, und Nachrichtenverarbeitung, z.B. Storm oder Flink.

Nachrichten sind ein wesentlicher Bestandteil der Schnittstelle solcher Dienste. Wie bei jeder anderen Schnittstelle machen wir uns vor der Entwicklung Gedanken, wie wir sie gestalten, technisch und fachlich. Bei Nachrichten legen wir fest, welche Eigenschaften so eine Nachricht hat. Nachrichten nutzen wir, um einen aktuellen Zustand oder eine Veränderung eines Zustandes zu melden. Nachrichten werden gruppiert (z.B. nach Ort oder Zeit), können zu größeren Nachrichten aggregiert oder in viele kleine Nachrichten zerlegt werden. Manche Nachrichten haben eine Gültigkeit und werden verworfen, wenn sie veraltet sind.

Motivation

Mit dem Baustein Event wollen wir Nachrichten eines Systems beschreiben, weitestgehend unabhängig vom Architekturstil und der gewählten technischen Lösung. Dabei steht der fachliche Nutzen der Nachricht im Vordergrund. In einem agilen Projekt können wir die Entscheidung für die technische Umsetzung getrost dem cross-funktionalen Team überlassen.  Die Technologie für die Nachrichtenverteilung und Nachrichtenverarbeitung hat große Auswirkungen auf die Realisierung von Nachrichten und muss immer durch eine Entscheidung mit dem Baustein Decision begründet werden.

Wichtig ist, dass der Baustein Event dafür gedacht ist, einer Nachricht eines Systems einen eindeutigen Namen zu geben. Der Name der Nachricht wird auch im Code verwendet und schlägt damit die Brücke zwischen Wiki und Code. Die Struktur einer Nachricht beschreiben wir direkt in der Klasse (z.B. javadoc) oder formal mit einem XML-, AVRO– oder JSON-Schema.

Code und andere Artefakte der Entwickler in einem Code-Repository sind somit Teil der Dokumentation. Ein Leser der Produktdokumentation wird durch den Baustein Event in die Lage versetzt, den Code für eine Nachricht zu finden und zu verstehen.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben des Architekturentwurfs definieren und Vorlagen für die Dokumentation zur Verfügung stellen.

Zuerst erfasst man ein “Architecture Principle”, welches die Nutzung von Nachrichten erklärt (das “Statement”) mit seinen Randbedingungen (das “Rationale”) und Auswirkungen (die “Implications”).

Das Kapitel 35 mit dem Titel “Architectural Artifacts” zeigt die unzähligen Möglichkeiten für die Darstellung des Systems (“View”) aus einer bestimmten Perspektive (“Viewpoint”) für einen bestimmten Aspekt der Funktionsweise des Systems (“Concern”).

Mit dem Begriff “Data Architecture” werden ganz konkret Diagramme vorgestellt, die geeignet sind, Nachrichten in allen Perspektiven, also statische und dynamische Sicht, darzustellen.

Quelle: TOGAF9 online documentation

(

In der Bausteinsicht wird die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Teilsysteme, Klassen, Interfaces, Pakete, Bibliotheken, Frameworks, Schichten, Partitionen, Tiers, Funktionen, Makros, Operationen, Datenstrukturen, …) sowie deren Beziehungen dokumentiert. Nachrichten sind in erster Linie Datenstrukturen. Das Zusammenspiel der Bausteine wird in der Laufzeitsicht beschrieben.

Quelle: ARC42 online documentation

Definition

Was beschreibt der Baustein Entity?

Unabhängig vom Architekturstil gibt es in jedem System Fachklassen bzw. ganz allgemein Informationsobjekte. Diese Objekte sind Datenspeicher (“etwas, das existiert”) oder repräsentieren einen aktuellen Zustand im System. Ein Informationsobjekt ist häufig mit einer Identität verbunden. Jede Software hat zum Ziel, Probleme innerhalb eines Fachgebiets – der Domäne – für ihre Nutzer zu lösen. Beim Domain-Driven Design (kurz DDD) geht es nicht nur um die technische Umsetzung, sondern auch um unsere Denkweise beim Entwurf des Systems. DDD zusammen mit CARDS+ eröffnet weitere Optionen. Informationsobjekte (Entity und Aggregate) aus dem DDD sind eine ideale Ergänzung zum entsprechenden Begriff im Glossar. Das ist immens wichtig für die Bildung eines gemeinsamen Vokabulars im Projekt. Die gemeinsame Sprache ist ein wichtiges Ziel von CARDS+ und DDD.

Spannend ist noch die Frage, ob wir bei der Implementierung des Domänenmodells die Begriffe ins Englische (der lingua franca der Entwickler) übersetzen sollen. Meine persönliche Empfehlung ist, keinen Begriff der Domäne zu übersetzen. Eine Übersetzung ins Englische widerspricht der Idee, dass Entwickler und Domänenexperten die selbe Sprache sprechen.

Motivation

Mit dem Baustein Entity wollen wir Informationsobjekte eines Systems beschreiben, weitestgehend unabhängig vom Architekturstil und der gewählten technischen Lösung. Dabei steht der fachliche Nutzen des Objektes im Vordergrund. In einem agilen Projekt können wir die Entscheidung für die technische Umsetzung getrost dem cross-funktionalen Team überlassen. Die Technologie für die Persistenz hat große Auswirkungen auf die Realisierung von Informationsobjekten und muss immer durch eine Entscheidung mit dem Baustein Decision begründet werden.

Wichtig ist, dass der Baustein Entity dafür gedacht ist, einem Informationsobjekt einen eindeutigen Namen zu geben. Der Name des Objektes wird auch im Code verwendet und schlägt damit die Brücke zwischen Wiki und Code. Die Struktur des Objektes beschreiben wir direkt in der Klasse (z.B. javadoc) oder formal mit einem XML-, AVRO– oder JSON-Schema.

Code und andere Artefakte der Entwickler in einem Code-Repository sind somit Teil der Dokumentation. Ein Leser der Produktdokumentation wird durch den Baustein Event in die Lage versetzt, den Code für eine Nachricht zu finden und zu verstehen.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben des Architekturentwurfs definieren und Vorlagen für die Dokumentation zur Verfügung stellen.

Zuerst erfasst man ein “Architecture Principle”, welches beispielsweise den Einsatz des Domain-Driven Design erklärt (das “Statement”) mit seinen Randbedingungen (das “Rationale”) und Auswirkungen (die “Implications”).

Das Kapitel 35 mit dem Titel “Architectural Artifacts” zeigt die unzähligen Möglichkeiten für die Darstellung des Systems (“View”) aus einer bestimmten Perspektive (“Viewpoint”) für einen bestimmten Aspekt der Funktionsweise des Systems (“Concern”).

Mit dem Begriff “Data Architecture” werden ganz konkret Diagramme vorgestellt, die geeignet sind, Informationsobjekte in allen Perspektiven, also statische und dynamische Sicht, darzustellen.

Quelle: TOGAF9 online documentation

In der Bausteinsicht wird die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Teilsysteme, Klassen, Interfaces, Pakete, Bibliotheken, Frameworks, Schichten, Partitionen, Tiers, Funktionen, Makros, Operationen, Datenstrukturen, …) sowie deren Beziehungen dokumentiert. Nachrichten sind in erster Linie Datenstrukturen. Das Zusammenspiel der Bausteine wird in der Laufzeitsicht beschrieben.

Quelle: ARC42 online documentation

Definition

Was beschreibt der Baustein Task?

Komplexe IT-Systeme bestehen aus Software, Middleware und Hardware. Der Betrieb eines IT-Systems stellt nicht erst seit der Idee der DevOps eine große Herausforderung an eine Betriebsorganisation. Moderne Systeme sind heterogen in vielerlei Hinsicht. Software wird von den Entwicklern in verschiedenen Programmiersprachen entwickelt. Eine Architektur mit Microservices oder die Verwendung der Cloud führt zu einer Vielzahl von Komponenten, die mit unterschiedlichen Technologien realisiert werden. Datenbanken haben relationale Modelle oder sind dokumenten- oder graphenbasiert. Verteilte Datenverarbeitung mit Events oder Microbatches spielt durch den Bedarf an Big-Data-Lösungen eine immer größere Rolle. Die Liste ließe sich noch fortsetzen.

Motivation

Die Anforderungen an die Betriebsorganisation sind dementsprechend hoch. Sie müssen mit der Vielzahl von Technologien umgehen können, häufig in einer produktspezifischen Art und Weise. Speziell in der agilen Software-Entwicklung werden immer wieder neue Technologien eingesetzt. Treiber sind in der Regel Qualitätsanforderungen (z.B. Sicherheit, Robustheit oder Skalierung). Nicht immer berücksichtigen Entwickler, dass es später jemanden gibt, der das veränderte Produkt betreibt und wissen muss, wie das genau geht.

Ob durch personelle Fluktuation, Schichtbetrieb oder Teilzeitbeschäftigung der Mitarbeiter, in einer Betriebsorganisation wechselt das Personal. Es kann daher immer passieren, dass unter Umständen ein Mitarbeiter ohne Erfahrung zu einer unpassenden Zeit (z.B. Wochenende oder in der Nacht oder beides) eine ganz normale Regelaufgabe ausführen muss. Eine passende Betriebsanweisung ist dann Gold wert und verschafft dem Operator die notwendige Handlungssicherheit.

Besonders wichtig ist die Sicherung des Wissens über jene Aufgaben, die ein Operator durch eine Automatisierung in der Regel nicht manuell durchführt. Solche Aufgaben kann er nicht trainieren. Trotzdem muss er im Fall der Fälle bei einer manuellen Ausführung alle notwendigen Handlungsschritte in der richtigen Reihenfolge ausführen.

Mit Betriebsanweisungen bekommt die Betriebsorganisation eine Dokumentation an die Hand, mit der sie der Herausforderung für den Betrieb eines IT-Systems begegnen kann. Durch die Idee der DevOps und die frühzeitige Berücksichtigung des Betriebs der technischen Komponenten schon während der agilen Software-Entwicklung wird die Qualität der Betriebsanweisungen gesteigert.

Betriebsanweisungen der Kategorie Aufgabe sind

  • manuell durchzuführende Regelaufgaben.
  • automatisiert ausgeführte Regelaufgaben.
  • vorbereitete Sonderaufgaben.

Betriebsanweisungen der Kategorie Analyse beschreiben in den Handlungsschritten beispielsweise

  • Vorgefertigte Grep- oder Awk-Befehle für die Analyse von Log-Dateien
  • Anweisungen für die Auswertung von Log-Daten (z.B. in Kibana)

Betriebsanweisungen der Kategorie Alarm haben offensichtlich nur einen Zweck: Sie beschreiben, was muss ein Operator tun muss, wenn durch die Überwachung des IT-Systems eine bestimmte Situation erkannt wird und ein Alarm ausgelöst wird. In den Handlungsschritten werden bereits existierende Betriebsanweisungen der Kategorien Aufgabe oder Analyse wiederverwendet.

Definition