In zehn Folgen haben wir Ihnen in dieser Kolumne REQ4ARCS nahegebracht – das, was Architekt*innen über Requirements wissen sollten, wenn sie erfolgreiche Systeme oder Produkte bauen und deployen wollen. In dieser (vorläufig letzten) Folge zeigen wir Ihnen im Überblick nochmals die wichtigsten Themen in Kurzform. Als Ausgangspunkt nutzen wir die sechs Hauptaufgaben aus arc42, die Sie in Ihrer Architektenrolle bearbeiten sollen (Abb. 1) und konzentrieren uns im Folgenden auf das Thema „Anforderungen und Randbedingungen klären“.

In einer der letzten Folgen haben wir bereits über beispielhafte Spezifikationen geschrieben. Diesmal möchten wir konkreter auf die Möglichkeiten der Ausführbarkeit solcher Spezifikationen eingehen. Dazu werden wir einen Ausflug in die großartigen Möglichkeiten von Behavior-driven Development unternehmen.

In der letzten Folge hatten wir das Thema „Qualität“ top-down erklärt und Ihnen dazu das generische Qualitätsmodell von ISO 25010 vorgestellt – zur Erinnerung finden Sie in Abbildung 1 nochmal die obere Ebene der Qualitätseigenschaften zusammengefasst – das komplette Modell geht noch eine Stufe tiefer und umfasst insgesamt gut 45 solcher Eigenschaften. Das ergibt eine ziemlich breite Themenvielfalt rund um „Qualität“, ist aber als Grundlage für konkrete Architektur- oder Implementierungsentscheidungen viel zu abstrakt: Wir benötigen mehr Details, wir müssen genauer wissen und beschreiben, was Stakeholder denn nun wirklich von unseren Systemen erwarten oder benötigen. Abstrakte Begriffe wie „Performance“ genügen dazu nämlich nicht.

In den vergangenen drei Folgen haben Sie erfahren, wie Sie systematisch mit funktionalen Anforderungen umgehen können. Sie wissen jetzt, wie Sie die richtigen fachlichen Prozesse mitsamt den dafür notwendigen fachlichen Daten ermitteln und kommunizieren, Sie kennen User Stories, Abläufe und Features. Ihre Anwendung kann jetzt (beispielsweise) Kinokarten verkaufen. Aber da war doch noch was: Die Zahlungen der Kinokarten sollen gegen unbefugte Zugriffe geschützt und vor allen Dingen nicht-abstreitbar erfolgen (Stichwort: IT-Sicherheit). Außerdem muss der gesamte Bezahlvorgang in weniger als dreißig Sekunden abgeschlossen sein (Stichworte: Performance) und natürlich niemals ausfallen (Stichwort: Zuverlässigkeit). Diesen schwierigen Themen wenden wir uns in den nächsten Folgen zu – den Qualitätsanforderungen.

In den letzten Folgen haben wir Ihnen Optionen für die Darstellung und Klärung funktionaler Anforderungen aufgezeigt. Eingestiegen sind wir über Geschäftsprozesse und haben anschließend die Granularität in kleinen Schritten bis zu User Stories verfeinert [1]. In der letzten Folge haben Sie dann einige Aspekte des Knowledge Crunchings aus dem Domain-driven Design kennengelernt, insbesondere Event Storming und die Ubiquitous Language [2]. Nun stellen wir Ihnen noch eine dritte Perspektive für funktionale Anforderungen vor, nämlich Beispiele.

In der vorigen Folge haben Sie gesehen, wie wir Überblick über die wesentlichen funktionalen Anforderungen bekommen können – nämlich indem wir von groben Zielen ausgehend die Granularität von Anforderungen verfeinern und dabei Geschäftsprozesse und Ende-zu-Ende-Abläufe (Use Cases oder User Stories) untersuchen. In dieser Folge möchten wir das Thema Domain-driven Design (DDD) aufgreifen und auf dessen Ansätze in puncto „Requirements“ eingehen.

In der vorigen Folge haben wir uns Scope angesehen. Der saubere Start hat also geklappt. Wir haben uns auf Ziele, Stakeholder und Scope geeinigt. Jetzt wollen wir die Anforderungen verstehen und klären – und zwar sowohl die funktionalen Anforderungen als auch Qualitätsanforderungen und Randbedingungen.

In der vorigen Folge haben wir Ihnen drei Zutaten vorgestellt, die Sie als Architekt(in) von anderen auf jeden Fall einfordern sollten, bevor Sie mit Designentscheidungen loslegen: klare Ziele, die Kenntnis der Stakeholder und die Festlegung Ihres Scopes. Starten wir mit dem Scope.

In der zweiten Folge unserer Kolumne stellen wir Ihnen drei Zutaten vor, die Sie als Architekt(in) von anderen auf jeden Fall einfordern sollten. Wir nennen das zusammenfassend einen „Clean Start“ für Ihr Projekt oder Ihre Produktentwicklung. Für den Fall, dass das nicht klappt, kennen Sie ja Ihr Schicksal: Dann müssen Sie diese Teile der Analysearbeit auch noch selbst in die Hand nehmen.

Nachdem Sie von uns über die letzten Jahre in zahlreichen Ausgaben des „Knigge für Softwarearchitekten“ hoffentlich ein paar Ideen für gute Lösungsfindung bekommen haben [1], geht es in dieser neuen Kolumne um ein Dilemma. Das Dilemma diesmal: Softwarearchitekten und Entwickler leiden immer wieder unter schlechten beziehungsweise fehlenden Anforderungen für ihre Arbeit. Dabei finden Entwicklungsteams für praktisch jedes Problem eine vernünftige Lösung – sofern sie wissen, wo genau das Problem liegt [2].

Wir zeigen Ihnen in dieser Folge, wie Sie statische Websites mithilfe von AsciiDoc erstellen und pflegen können. Dazu greifen wir etwas tiefer in die Werkzeugkiste der Softwareentwicklung, nämlich zum Ruby-basierten Generator Jekyll. Jekyll selbst verwendet standardmäßig Markdown als Auszeichnungssprache, für AsciiDoc müssen wir ein klein wenig nachhelfen. Alternative Ansätze diskutieren wir im Textkasten „Alternativen zu Jekyll“.

In Folge 3 unserer Kolumne hatten wir die Generierung von PDFs aus AsciiDoc bereits kurz angerissen. In dieser Folge gehen wir auf ein paar Details ein, mit denen Sie die Klippen bei der Erstellung von PDFs gezielt umschiffen können (und davon gibts leider noch einige …).
 
 

„Jede hinreichend fortschrittliche Technologie ist von Magie nicht zu unterscheiden.“ Dieses Zitat von Arthur C. Clarke trifft auf vieles zu, was ein modernes Build-Skript stellenweise leistet. In dieser Folge unserer Kolumne lüften wir das Geheimnis und erklären einige der nützlichen Gradle-Features, die Sie für Ihre Dokumentation verwenden können. Sollte das Ihr erstes Date mit Gradle sein, empfehlen wir zuerst die Lektüre einer entsprechenden Einführung [1].

Eine Internetsuche nach den Stichworten „Asciidoc Tool“ liefert fürchterlich viele Treffer. Wir möchten den Dschungel der Möglichkeiten etwas lichten und Ihnen einige der weiter verbreiteten Werkzeuge kurz vorstellen. Dabei gehen wir vom konkreten Bedarf aus und möchten Tools vorstellen, die den Docs-as-Code-Ansatz konkret unterstützen.

Ein halbes Dutzend Folgen dieser Kolumne, bevor wir endlich zum Thema Sourcecode kommen: Wir möchten in Architekturdokumentation an manchen Stellen Code integrieren, etwa zur Beschreibung wichtiger Schnittstellen. AsciiDoc bietet hierfür schicke Features. Wie immer finden Sie den Quellcode dieser Kolumne online hier.

Wenn es um die Modellierung von Architekturen geht, also dem Erstellen eines Modells mit verschiedenen Sichten anstelle von unkorrelierten Zeichnungen, dann reicht das Einbinden von statischen Diagrammen oder PlantUML nicht mehr aus. Deshalb greifen wir in dieser Folge etwas tiefer in den Werkzeugkasten und integrieren echte Modelle in unseren Docs-as-Code-Ansatz.

Architekturdokumentation besteht hauptsächlich aus Fließtext, Tabellen und Diagrammen. Fließtext und Tabellen sollten nach der letzten Folge kein Problem mehr sein. Jetzt zeigen wir Ihnen mehrere Optionen, Diagramme in Ihre Dokumentation zu integrieren: Einerseits den einfachen Weg des Referenzierens (mit einigen möglichen Optionen) und alternativ Diagrams-as-Code, was gut zu Titel und Inhalt dieser Kolumne passt. So viel sei allerdings schon verraten: Leider eignet sich der letztgenannte (PlantUML-basierte) Ansatz nur für ganz wenige Arten von Diagrammen. Aber eins nach dem anderen – fangen wir mit den einfachen Dingen an.

In den letzten Ausgaben haben wir gezeigt, wie Sie AsciiDoc-Dokumente modular aufbauen und in verschiedene Zielformate wie PDF, DOCX oder Confluence konvertieren können. Diesmal gehen wir auf ein paar der Features von AsciiDoc ein, die unserer Meinung nach bei Architekturdokumentation nützlich sein können.

In der letzten Folge dieser Kolumne haben wir gezeigt, wie Sie Ihre AsciiDoc-Dokumente modular aufbauen können. In der dritten Folge der Kolumne erklären wir am Beispiel der Formate PDF, DOCX, Confluence und EPUB, wie sich verschiedene Ausgabeformate aus Ihrem AsciiDoc-Input erzeugen lassen.

In der letzten Ausgabe haben wir gezeigt, wie Sie mithilfe von AsciiDoc schnell zu ordentlich gestalteten Dokumenten kommen können. In der zweiten Folge unserer Kolumne möchten wir Ihnen Strukturierung und Modularisierung von Dokumentation vorstellen, einerseits zur Erleichterung von Teamarbeit, andererseits zur Verwendung einzelner Dokuteile für verschiedene Zielgruppen.