Struktur
cards+ für Ordnung mit System
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.
Systembeschreibung
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, besonderer Situationen und bekannter und akzeptierter Fehler des IT-systems.
Systemstruktur
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 Applikationsserver.
Architekturentwurf
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 des Architekturentwurfes ist die Darstellung und Kommunikation des Architekturstils.
Das Metamodell der Bausteine der Produktdokumentation.
Struktur
Das Metamodell der Bausteine
Das Metamodell der Bausteine einer Produktdokumentation richtet sich an jene Personen, die ein abstraktes Modell für das Verständnis der Zusammenhänge brauchen. Das Metamodell soll eine Orientierung für den Einsatz von cards+ und der effektiven Verwendung der Bausteine im Wiki sein.
Die Bausteine der Systemstruktur orientieren sich auch 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. Kontextgrenzen werden in den Bausteinen Domain (Gruppierung eng verwandter Dienste und Objekte) und Service (z.B. für die Gruppierung der Microservices eines Dienstes) definiert.
Vereinfachtes Metamodell
Die Bausteine der Systembeschreibung sind streng hierarchisch strukturiert und unterstützen so die Arbeitsweise top down bei der Analyse. Das bedeutet, dass ein Autor die Grenzen der Software im Baustein Topic beschreibt. In seiner weiteren Analyse der Fähigkeiten der Software gibt er im Baustein Epic einen Überblick. Den Baustein Case nutzt er, um jede einzelne Fähigkeit der Software zu erfassen und mit den Essenzschritten in der Lösung den Übergang zu den Bausteinen der Systemstruktur zu schaffen.
Die Bausteine der Systemstruktur haben das Ziel, die Struktur der Software abzubilden. Abhängig vom Architekturstil ergeben sich durch den Baustein Domain Gruppen von Diensten (Baustein Service) und Objekten (Bausteine Event bzw. Entity). Der Baustein Task ist Platzhalter für Handlungsanweisung, die eine Betriebsorganisation braucht, um einen unterbrechungslosen und störungsfreien Betrieb des IT-Systems zu gewährleisten.
Die Bausteine für den Architekturentwurf schaffen einen Rahmen für fundamentale Entscheidungen, Konzepte und Richtlinien. Die Bausteine Decision Und Spec haben die Aufgabe, den Architekturstil nachvollziehbar zu beschreiben. Das ist ein wichtiges Element der Kommunikation im Team und mit allen interessierten Parteien. Mit dem Baustein Policy bekommen Richtlinien einen festen Platz in der Produktdokumentation.
Qualität
cards+ hat prüfbare Regeln
Die Produktdokumentation umfasst das gesamte Wissen zu einem Produktinkrement. Sie beschreibt den Zustand eines Produktes zu einem bestimmten Zeitpunkt. Sie ist nicht auf das Wiki beschränkt. Das Wiki bildet jedoch 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.
Methode
Das »missing link« der Dokumentation
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 (Service) und Objekte (Event bzw. Entity) an der Lösung einer Fähigkeit der Software (Case) in der Software beteiligt sind.
- Ein Tester kann einschätzen, welche Fähigkeit der Software (Case) sich auf einen Dienst (Service) auswirkt, für die er Testfälle schreibt.
- Ein Entwickler kann den fachlichen Kontext (Topic, Epic und Case) eines Dienstes (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.