cards+ hilft bei der Einführung und Durchsetzung einer Struktur für die Produktdokumentation im Wiki. Die Bausteine von cards+ sind hierarchisch strukturiert. «Domain-Driven Design» war eine wichtige Inspiration. Bausteine stellen Vorgaben für viele Arten dokumentierter Informationen für Autoren dar, wie es sie auch in Form von Programmierrichtlinien für Entwickler gibt.
Viele Teams starten mit der Absicht, ihre Software zu dokumentieren. Anfangs sind Entwickler motiviert, ihr Wissen auch schriftlich zu teilen. Ein Wiki macht es den Autoren auch sehr einfach. Ohne Regeln schreiben, formatieren und gliedern sie ihre Beiträge unterschiedlich. Die Folge ist, dass Leser Informationen nicht auf den ersten Blick finden.
Technische Redakteure kennen die Probleme. Und sie haben auch Lösungen. Technische Dokumentation entsteht in einem Team. Dokumentierte Informationen werden klassifiziert. Die Dokumentation ist hierarchisch aufgebaut. Dokumente sind miteinander verknüpft.
cards+ hilft bei der Einführung und Durchsetzung einer Struktur im Wiki. Die Lösungen der technischen Redakteure machen Inhalte in einem Wiki beherrschbar. Die Bausteine von cards+ orientieren sich an Konzepten, die Eric Evans in seinem Buch «Domain-Driven Design: Tackling Complexity in the Heart of Software» sehr ausführlich beschreibt. Das gilt im Besonderen für die gemeinsame Sprache (engl. ubiquitous language) und der Festlegung von Kontextgrenzen (engl. bounded context). Die gemeinsame Sprache findet bei cards+ Ausdruck durch das Glossar und die konsequente Verwendung der Seitentitel der Bausteine im Wiki entsprechend dem Prinzip COD.
In den Bausteinen der Systembeschreibung werden die Grenzen des IT-Systems definiert und alle Fähigkeiten der Software vollständig, widerspruchsfrei und hierarchisch erfasst. Fähigkeit ist der Sammelbegriff für Anwendungsfälle, besonderen Situationen und bekannten und akzeptierten Fehler eines IT-Systems.
Die Bausteine der Systemstruktur haben das Ziel, die Struktur der Software korrekt zu erfassen und einen Überblick über das Zusammenspiel der Dienste und Objekte zu geben. Ein nachrichten-orientierter Architekturstil ergibt eine andere Systemstruktur als die Realisierung eines IT-Systems mit einem monolithischen Applikationsservers.
In den Bausteinen für den Architekturentwurf werden die vom Auftraggeber geforderten Qualitätsmerkmale, fundamentale Entscheidungen und übergreifende Konzepte nachvollziehbar erfasst. Ein ganz wichtiges Ziel ist die Darstellung und Kommunikation des Architekturstils.
Das Metamodell
Ein Überblick.
Unter dem Sammelbegriff Systembeschreibung bündelt cards+ Bausteine für Fähigkeiten einer Software. Die Bausteine sind streng hierarchisch aufgebaut, vom Groben ins Feine. An der Spitze steht der Gegenstand (engl. topic, theme) für die Entwicklung. Die sehr abstrakte Sicht auf den Aufgabenbereich, in dem sich das Produkt bewegt, wird vollständig und widerspruchsfrei in Funktionalitäten und Fähigkeiten zerlegt. Zur Systembeschreibung zählen auch «Verständnismodelle», die wichtige Zusammenhänge aus fachlicher Sicht erklären.
Die Systembeschreibung ist keine Anforderungsdokumentation.
Der Produktverantwortliche nutzt die Bausteine der Systembeschreibung, um so früh wie möglich seine Vision des Produktes zu konkretisieren. Er tut das am besten bereits beim Start des agilen Entwicklungsprojektes, unter Einbeziehung des Auftraggebers. Er hat die Möglichkeit, produktspezifische Funktionalitäten und Fähigkeiten der Software frühzeitig einen Namen zu geben. Ein guter Titel legt so den Grundstein für eine gemeinsame Sprache von Auftraggeber, Produktverantwortlichen und dem Team. Interessierte Parteien können sich später jederzeit einen sehr kompakten Überblick über den Umfang des Produktes verschaffen.
Der Baustein Topic beschreibt einen klar abgegrenzten Aufgabenbereich (engl. scope), in dem das IT-System Verwendung findet. Er vermittelt einen Überblick und nimmt Bezug auf die Unternehmensprozesse. Er bündelt eine mit den Anforderungen wachsende Menge von Funktionalitäten, die im Detail mit dem Baustein Epic dokumentiert werden.
Der Baustein Epic gibt einer produktspezifischen Funktionalität einen eindeutigen Namen und enthält eine fachliche Beschreibung. Er bündelt eine mit den Anforderungen wachsende Menge von fachlich verwandten Fähigkeiten, besonderen Situationen und bekannten akzeptierten Fehlern, die im Detail mit dem Baustein Case dokumentiert werden.
Zurück zur Übersicht
Unter dem Sammelbegriff Systemstruktur bündelt cards+ Bausteine für Dienste und Objekte. Sie haben das Ziel, die Struktur der Software zu erfassen und einen Überblick über das Zusammenspiel von Diensten und Objekten zu geben.
Software architecture is loosely defined as the organizational structure of a software system including components, connections, constraints and rationale.
— —Paul Clement
Was Paul Clement hier beschreibt, ist ein wesentlicher Treiber für die Bausteine der Systemstruktur. Auch die Idee des “domain driven design” wird in cards+ berücksichtigt und spiegelt sich in den Namen der Bausteine wider. Das Ziel der Etablierung einer gemeinsamen Sprache verfolgen beide Ansätze.
Ein Punkt ist besonders wichtig: Entwickler brauchen keine Dokumentation, die im Detail erklärt, wie Code funktioniert. Nur im Code steckt die volle Wahrheit! Das ist eine Tatsache, die Autoren akzeptieren und zu ihrem Vorteil verwenden, indem sie lesbare Teile vom Code, Code-Kommentare und code-nahe Artefakte als dokumentierte Information in die Produktdokumentation aufnehmen.
Daher gilt immer: Programmieren ist dokumentieren!
Alle Details zur Implementierung befinden sich einer Spezifikation. Das Wiki ist der Ort der Veröffentlichung dieser Spezifikation. Sie muss jedoch nicht im Wiki gepflegt werden.
Im Steckbrief der Bausteine der Systemstruktur gibt es immer eine Kurzbeschreibung. Ganz allgemein geht es in den Bausteinen um die Sicherung von Wissen, das gar nicht oder nur sehr schwer aus dem Code herausgelesen werden kann, als wertvolle Ergänzung zur Spezifikation, die immer aus der Code-Basis stammt.
Der Baustein Layout enthält Entwürfe oder Skizzen eines Teils der Bedienoberfläche. Layout ist der Oberbegriff für eine ganze Reihe spezialisierter Ausprägungen, z.B. Ansicht und Dialog in einer Website oder Screen in einer Smartphone-App. Window, Panel, Prompt und Widget, u.s.w. sind wiederverwendbare Muster in einem Layout.
Zurück zur Übersicht
Der Architekturentwurf ist ein Sammelbegriff für Dokumentation, mit der Autoren geforderte Qualitätsmerkmale, wichtige Entscheidungen und übergreifende Konzepte beschreiben.
Software architecture is the set of design decisions which, if made incorrectly, may cause your project to be cancelled.
— —Eoin Woods
Eoin Woods sagt, dass die Architektur allein dadurch ausreichend genau dokumentiert ist, wenn alle Entscheidungen bekannt sind, die eine Gefahr für Produkt oder Projekt darstellen, wenn sie falsch waren. cards+ geht hier mit seinen Bausteinen des Architekturentwurfs einen Schritt weiter.
Auftraggeber und Produktverantwortliche machen Vorgaben, die häufig große Auswirkung auf die Entwicklung des Produktes haben. Solche Vorgaben werden dadurch charakterisiert, dass sie den Lösungsraum für die Entwicklung des Produktes einschränken. Gerade bei jene Entscheidungen eines Auftraggebers, die etwas ausschließen, ist ein Nachweis besonders wichtig. Qualitätsmerkmale, auch bekannt als nicht funktionale Aspekte, legen fest, unter welchen Rahmenbedingungen Funktionen eines Systems ausgeführt werden sollen. Qualitätsmerkmale werden nicht einfach programmiert. Sie sind Eigenschaften, die durch die Wahl des Architekturstils, durch den Einsatz bestimmter Infrastrukur oder Anwendung bestimmter Entwurfsmuster bestimmt werden.
Der Baustein Concept wird verwendet, um ein wiederkehrendes Entwurfsmuster bei der Implementierung (engl. software pattern) oder ein übergreifendes Konzept produktspezifisch zu beschreiben. Besonderes Augenmerk liegt dabei auf den Qualitätsmerkmalen als Konsequenz der gewählten Lösung.
Mit dem Baustein Module lassen sich Eigenschaften, Einschränkungen und Besonderheiten von Software erfassen, die beim Aufbau eines individuellen Produktes vom Team genutzt, aber nicht selbst realisiert werden. Modul ist der Sammelbegriff für «fremde» Bestandteile eines Produktes. Besonderes Augenmerk liegt dabei auf den Qualitätsmerkmalen des Moduls und die damit verbundenen nicht funktionalen Aspekte.
Zurück zur Übersicht
Die Produktdokumentation umfasst das gesamte Wissen zu einem Produktinkrement. Sie beschreibt den Zustand eines Produktes zu einem bestimmten Zeitpunkt.
Das Wiki ist das zentrale Verzeichnis für die Dokumentation.
Eine vollständige Produktdokumentation muss als solche erkennbar sein. Autoren brauchen prüfbare Regeln für den Aufbau und Inhalt im Wiki in einer klar kommunizierten Struktur mit vordefinierten Bausteinen. Jeder Baustein hat genau einen Zweck und bestimmte Zielgruppen. Autoren wissen, was in den Baustein gehört und was nicht. Diese Abgrenzung ist sehr wichtig.
Die exakte Definition der Bausteine ist Autoren und Lesern gleichermaßen bekannt. Bausteine stellen Vorgaben für Autoren dar, wie es sie auch in Form von Programmierrichtlinien für Entwickler gibt. cards+ unterstützt so Autoren bei dem Vorhaben, die Seiten im Wiki aktuell und fehlerfrei zu halten. Leser aus der Projektorganisation können durch die einheitliche Gestaltung der Bausteine den Inhalt besser einordnen. So können sie zielgerichtet Feedback geben.
In der Systembeschreibung zeigt sich der Problemraum des Produktes. Dieser Teil der Dokumentation ist das Abbild der Realität, die Wirklichkeit aus Sicht der Nutzer des IT-Systems. Je mehr ein Team über die Welt weiß, in dem die Software eingesetzt wird, desto besser wird die Lösung.
Die tatsächlich realisierte Software beschreibt der Produktverantwortliche in Abstimmung mit dem Team und unterstützt durch Vertreter des Teams mit den Bausteinen der Systemstruktur und des Architekturentwurfs. Bei agiler Entwicklung schreitet die Produktdokumentation im Gleichschritt mit dem Produkt voran. Das Ende einer Iteration ist der Zeitpunkt, an dem Produktdokumentation, Code und Testpläne eine Einheit bilden: Das Produktinkrement.
Das «missing link» der Produktdokumentation ist der Baustein Case. Er bildet den Übergang der Systembeschreibung in die Systemstruktur und umgekehrt.
- Ein Produktverantwortlicher kann aus seiner fachlichen Sicht ableiten, welche Dienste (Baustein Service) und Objekte (Bausteine Event bzw. Entity) an der Lösung einer Fähigkeit der Software (Baustein Case) beteiligt sind.
- Ein Tester kann einschätzen, welche Fähigkeit der Software (Baustein Case) sich auf einen Dienst (Baustein Service) auswirkt, für die er Testfälle schreibt.
- Ein Entwickler kann den fachlichen Kontext (Bausteine Topic, Epic und Case) eines Dienstes (Baustein Service) für sein Verständnis herausfinden.
Der Baustein Case hat den Abschnitt Ausgangslage, in dem der Produktverantwortliche eine einzelne, nicht weiter teilbare Fähigkeit der Software beschreibt. Nach Abschluss der Realisierung einer Fähigkeit ergänzen er oder ein Vertreter des Teams die gewählte Lösung in Form von Essenzschritten. Diese kompakte Liste beschreibt die Lösung als eine Art «Pfad» durch die Software, eine Art «Navigation» durch die Komponenten und Datenflüsse des IT-Systems.
Der Baustein Topic gibt den Umfang (engl. scope) des Produktes vor. Hier wird Bezug auf die Unternehmensprozesse genommen.
Der Baustein Epic gruppiert verwandte Fähigkeiten zu Funktionalitäten. Hier befinden sich auch Ausschlüsse und Abgrenzungen.
Der Baustein Case beschreibt eine einzelne geforderte Fähigkeit der Software und nach dem Abschluss der Realisierung mit den Essenzschritten die Lösung.
Mit dem Baustein Decision werden vom Auftraggeber geforderte Qualitätsmerkmale der Software mit Begründung festgehalten.
Der Baustein Layout wird für die Sicherung der Entwürfe einer Bedienoberfläche verwendet, die mit dem Auftraggeber abgestimmt wurden.
Den Baustein Service dient der Festlegung von Schnittstellen des IT-Systems nach außen. Er beschreibt das API und die Endpunkte auf beiden Seiten.