Prozesse
Einführung in die Produktdokumentation
Die Zielgruppe sind Personen, die neu in der Projektorganisation sind. Die Teilnahme ist unabhängig von ihrer Rolle im Projekt. Interesse ist aber Voraussetzung. Die Veranstaltung dauert 45 Minuten. Es ist ein Frontalvortrag des Gärtners im Projekt. Maximal 15 Minuten sind für Fragen während der Einführung und für Feedback danach vorgesehen. Damit dauert die Einführung maximal eine Stunde.
Das folgende Protokoll macht Vorschläge, was ein Vortragender über eine Produktdokumentation mit cards+ erzählen kann. Passend dazu gibt es eine schrittweise Anleitung für die Gestaltung des Whiteboards.
Produktdokumentation
Eine Produktdokumentation hat das Ziel, den Zustand eines Produktinkrementes so exakt wie möglich zu beschreiben. Sie exisiert im Wiki und wird von Autoren genutzt, um Produktwissen und Ergebnisdokumente der nachhaltig zu sichern. Sie bildet das zentrale Verzeichnis für Spezifikationen, Testpläne und anderer für das Produkt relevanten Unterlagen. Sie wird über die gesamte Lebenszeit eines Produktes gebraucht. Bei sehr erfolgreichen Produkten sind das Jahrzehnte.
Ein Produkt entsteht oder wächst, indem Visionen und Ideen eines Produktverantwortlichen durch sein Team in Software transformiert werden. Das Ende einer Iteration ist der Zeitpunkt, an dem Produktdokumentation, Code und Testpläne eine Einheit bilden: Das Produktinkrement.
Eine Produktdokumentation zerfällt im Wiki grundsätzlich in die Bereiche Systembeschreibung, Systemstruktur und Architekturentwurf.
Bausteine der Systembeschreibung
In den Bausteinen der Systembeschreibung geht es konkret um den Versuch, alle Fähigkeiten des Produktes vollständig und widerspruchsfrei zu erfassen. Sie besteht aus der Dokumentation der Anwendungsfälle, besonderer Situationen und bekannter und aktzeptierter Fehler des Produktes.
Mit dem Baustein Topic wird der Umfang (engl. scope) des Produktes im Überblick beschrieben. Der Baustein Epic enthält eine fachliche Beschreibung einer Funktionalität des Produktes. Der Baustein Case enthält eine fachliche Beschreibung einer einzelnen Fähgigkeit des Produktes und die Essenzschritte der gewählten Lösung.
Bausteine der Systemstruktur
Die Bausteine der Systemstruktur haben das Ziel, die Struktur der Software zu erfassen, mit Hinweisen zur Implementierung im Steckbrief und einer kompakten Beschreibung für das “Verständnis”. Sie geben Diensten und Objekten des IT-Systems eindeutige Namen. Ein Komponentenüberblick ist eine grafische Visualisierung der Topologie der Dienste mit ihren Datenflüssen, verknüpft mit den entsprechenden Seiten im Wiki. Kritische Pfade oder gefährliche Rückkopplungen im Zusammenspiel der Dienste lassen sich so besser erkennen.
Mit dem Baustein Domain geben Autoren einer Zusammenstellung von Diensten und Objekten mit einer starken Kohäsion einen eindeutigen Namen. Mit dem Baustein Service beschreiben wir einen fachlichen Dienst. Mit dem Baustein Entity beschreiben Autoren ein fachlich relevantes Informationsobjekt. Mit dem Baustein Event beschreiben Autoren ein fachlich relevantes Nachrichtenobjekt. Der Baustein Layout enthält Entwürfe oder Skizzen eines Teils der Bedienoberfläche.
Bausteine für den Architekturentwurf
Die Bausteine für den Architekturentwurf erfassen Qualitätsmerkmale, Entscheidungen und Konzepte. Ein ganz wichtiges Ziel des Architekturentwurfes ist die Darstellung und Kommunikation des Architekturstils, der dem Produkt zugrunde liegt.
Der Baustein Decision wird verwendet, um konsequent alle fundamentalen technischen Entscheidungen oder vom Auftraggeber geforderten Qualitätsmerkmale, deren Rücknahme bzw. Veränderung große Auswirkung auf das Produkt haben, zu dokumentieren.
Der Baustein Spec wird verwendet, um ein wiederkehrendes Entwurfsmuster bei der Implementierung (engl. software pattern) oder ein übergreifendes Konzept produktspezifisch zu beschreiben. Produkte anderer Hersteller oder Open-Source-Software wird ebenfalls mit dem Baustein Spec dokumentiert, weil entweder spezifische Konzepte mit ihrem Einsatz verbunden sind oder die Verwendung aufgrund bekannter Probleme eingeschränkt wird.
Spezifikationen im Wiki veröffentlichen
Bestimmte Teile vom Code sind geeignet als Dokumentation. Sie enthalten durch Kommentare (z.B. javadoc) wichtiges Wissen. Gleiches gilt für code-nahe Artefakte. Eine Konfigurationsdatei zeigt sehr genau, welche Parameter es gibt. Eine Schemadatei beschreibt ein Informations- oder Nachrichtenobjekt ganz exakt. Das Team vermeidet Dokumentation, wenn sie diese Entwicklungsergebnisse für die Veröffentlichung im Wiki nutzbar machen. Manche code-nahen Artefakte können direkt ins Wiki hochgeladen werden, wenn sie vom Team “lesbar” gestaltet werden. Andere Teile vom Code benötigen eine Konvertierung in eine im Wiki verwendbares Format (z.B. asciidoc).
Testpläne im Wiki veröffentlichen
Testpläne, organisiert in einer Testpyramide, sichern die Qualität der Software ab. Der Baustein Case beschreibt eine Fähigkeit der Software, die mit mindestens einem Testfall abgesichert wird. In einem Testfall steckt daher auch wichtiges Wissen. Das Team vermeidet Dokumentation, wenn sie einen Weg findet, die Testpläne in eine Form zu bringen, die im Wiki veröffentlicht werden kann.
Problemraum und Lösung
In den Bausteinen der Systembeschreibung wird der Problemraum («PR») des Produktes beschrieben. Sie geben Antwort auf die Fragen wer, wann und warum etwas mit dem Produkt tut. Dieser Teil der Dokumentation ist das Abbild der Realität, die Wirklichkeit aus Sicht der Nutzer des IT-Systems.
Die Bausteine der Systemstruktur beantworten hingegen die Frage, wie das Produkt realisiert wurde. Sie beschreiben die tatsächlich vom Team entwickelte Lösung («L»).
Die Bausteine für den Architekturentwurf beschreiben den Lösungsraum («LR») des Produktes. Der Baustein Decision zeigt nicht nur die gewählte Lösung, sondern auch Alternativen, die nicht weiter verfolgt werden. Mit dem Baustein Spec werden Entwurfsmuster beschrieben, die auch für zukünftige Implementierungen gelten.
Der Baustein Case ist das «missing link» der Produktdokumentation und bildet den Übergang der Systembeschreibung in die Systemstruktur und umgekehrt. Der Baustein Case verbindet ein konkretes Problem der Domäne («P») mit einer realisierten Lösung («L»).
Weitere Dokumente und Unterlagen
Das Glossar ist eine alphabetisch sortierte Sammlung von Fachbegriffen aus dem Projektumfeld. Das Glossar ist das “Wörterbuch” des Projektes. Es ist ein Mini-Lexikon, zugeschnitten auf das Produkt.
Eine Medienbibliothek ist ein Konzept, um Präsentationen (z.B. Powerpoint oder Keynote), Fotografien (z.B. Flipchart oder Whiteboard), Abbildungen und Diagramme in verschiedenen Formaten an einem zentralen “Ort” im Wiki abzulegen.
Die Linksammlung können wir verwenden, um extern verwaltete Dokumente und Unterlagen mit einem von uns gewählten Namen im Wiki zu verwenden.
Handlungsanweisungen beschreiben, wie das IT-System betrieben wird. Bei IT-Systemen spielt der Grad der Automatisierung eine wichtige Rolle. Für alle Tätigkeiten, die nicht automatisiert werden, gibt es Handlungsanweisungen. Sie beschreiben Tätigkeiten, die von geschultem Personal regelmäßig oder im Fall einer Störung ausgeführt werden.
Handbücher und Online-Hilfen geben aus der Perspektive der Nutzer Einblick in die Fähigkeiten des Produktes. Sie erklären den Nutzern den Einsatz des IT-Systems.
Die PDF-Datei wird mit dem PDF Embedder angezeigt.