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.

Dokumentation gehört zu den großen Übeln der Softwarezunft. Denn Software zu dokumentieren ist oft mühselig, zeitraubend und schlicht und ergreifend langweilig. Dass dem nicht so seien muss, zeigen die beiden Autoren Gernot Starke und Ralf D. Müller in ihrer neuen Kolumne. Ihr Ansatz ist die Dokumentation wie Code zu behandeln: Docs as Code.

Unserer Einschätzung nach werden Schnittstellen oft als Dinge dritter Klasse behandelt. Technologie auswählen, Features bauen und Bugs fixen gehen vor. Sogar Dokumentation schreiben scheint uns in manchen Projekten wichtiger als effektive Schnittstellen zu entwerfen. Wir wünschen Ihnen und uns die API-tektin, die gemeinsam mit Softwarearchitekten den Schnittstellen auf die Sprünge hilft.

In dieser Folge der Kolumne „Knigge für Software-Architekten“ stellt JAX-Speaker Gernot Starke eine Alternative für aufwändige Architekturbewertungen vor: Mikrobewertungen versprechen eine preiswerte und pragmatische Art, die Qualität von Produkten nachhaltig zu verbessern.

Ändern und erweitern unter Zeitdruck – das ist traurige Normalität für viele Softwerker. Ständig zwingen uns widrige Umstände oder dunkle Mächte dazu, mit zu wenigen Informationen oder zu wenig Zeit neue Features oder auch notwendige Änderungen suboptimal umzusetzen. Wir möchten gerne besser arbeiten, aber nur selten geben uns die dunklen Mächte die Chance dazu.

Der Flexibilisator implementiert seine Komponenten oder Systeme am liebsten so: generisch, möglichst auf viele zukünftige Gegebenheiten vorbereitet, universell einsetzbar und grenzenlos flexibel in alle Richtungen. Er findet den ultimativen Kick, wenn er über den beschränkten Spezialfall der aktuellen User Story hinaus quasi ein zeitloses Denkmal der Flexibilität erschaffen kann. Kennen Sie das auch, diesen Drang nach Verallgemeinerung, den tiefen Wunsch, etwas Großes zu schaffen? Wir möchten in dieser Folge zuerst etwas über mögliche Arten der Flexibilität von Software klarstellen, auf einige Vor- und Nachteile davon eingehen und anschließend kräftiges Bashing auf Flexibilisatoren betreiben.

Immer wieder jammern Kunden, dass Systeme schlecht seien und die IT die Anforderungen überhaupt nicht erfüllt habe. Entwicklungsteams verteidigen sich damit, dass ihnen niemand gesagt hat, was das Produkt wirklich können soll. Sie schieben die Schuld auf schlechte Anforderungen. Hätte man diese Wünsche rechtzeitig und klar geäußert, dann wäre die Lösung auch skalierbar, erweiterbar, performant und sicher. Fachbereiche oder Marketingabteilungen kontern: Es war doch klar, dass wir nach dem europäischen auch den asiatischen Markt erobern wollen. Selbstverständlich muss das Produkt leicht an neue Gesetze, Standards und Normen adaptiert werden können. Warum hätten wir das explizit sagen sollen?