Dokumentation ist ein Thema in jedem Entwicklungsprojekt. Abhängig vom Vorgehensmodell – agil, iterativ oder ganz klassisch mit Wasserfall – entstehen Lastenhefte, Pflichtenhefte, Studien, Grob- und Fachfeinkonzepte, fachliche und technische Spezifikationen, Entscheidungen, Richtlinien, Anleitungen, Vorgaben, Skizzen, Handbücher, um nur die bekanntesten Artefakte zu nennen, die zum großen Teil unter den Sammelbegriff Projektdokumentation fallen.

Der Begriff Produktdokumentation umfasst verschiedene Dokumente mit produktbezogenen Informationen, die für verschiedene Zwecke gebraucht oder gefordert werden. Die Zielgruppen, für die diese Dokumente erstellt werden, sind so unterschiedlich wie die Ziele, die mit der Dokumentation erreicht werden sollen.

CARDS+ unterstützt eine agile Projektorganisation, Wissensmanagement in einem Entwicklungsprojekt richtig zu organisieren, indem sie zielgerichtet und inkrementell Dokumentation entwickelt. Für Stakeholder und Projektmitarbeiter.

Durch Fluktuation oder durch Änderungen in der Organisation des Unternehmens entsteht ein regelmäßiger Wechsel bei den Projektmitarbeitern und bei allen anderen interessierten Parteien. Damit verbunden ist immer die Gefahr des Verlustes von Wissen. Der Verlust von Wissen in Entwicklungsprojekten ist gefährlich. Die Produktvision geht verloren. Qualität und Produktivität sinkt. Anpassungen und Erweiterungen der Software werden schwieriger. Analysten ist nicht klar, was die Software jetzt schon leistet. Entwicklerteams sind weniger motiviert, da sie in altem Code wühlen müssen, um zu verstehen, wie die Software “tickt”. Ihre Innovationskraft sinkt.

Auf dieser Seite befindet sich ein Überblick über die Beiträge in diesem Blog zur Methode CARDS+, thematisch geordnet.

Dokumentieren ist oft ein Reizwort in Projekten. Manchem wird zu viel dokumentiert, manche sehen Dokumentation als verzichtbar, andere wollen alles ganz genau beschreiben. In diesem Spannungsfeld bewegt sich die Methode CARDS+. Die wesentlichen Ziele sind:

CARDS+ hilft bei der Umsetzung des agilen Manifest, insbesondere geht es um den zweiten Punkt. Wir wollen nur das dokumentieren, was wir brauchen. Unser Ziel ist eine angemessene Dokumentation. Mit “wir” ist dabei die ganze Projektorganisation gemeint.

CARDS+ gibt eine sehr einfache Struktur für eine Produkdokumentation vor. Die Methode definiert eine feste Struktur und einige wenige Bausteine für ein Glossar, eine Systembeschreibung und die Architekturdefinition. Die Systembeschreibung besteht mindestens aus den Bausteinen Topic, Epic und Case. Die Architekturdefinition in seiner minimalen Form besteht aus den Bausteinen Decision und Service. Eine Medienbibliothek sorgt für Ordnung in Bildern und Diagrammen. Weitere Informationsquellen außerhalb des Wiki werden durch eine Linksammlung eingebunden.

CARDS+ ist kein Prozess, lässt sich aber sehr gut in Scrum integrieren. Jedes Dokument hat eine Zielgruppe und kann zu einem bestimmten Zeitpunkt im Verlauf des Projektes abgeschlossen und geprüft werden.

Ein unverzichtbares Werkzeug ist ein Wiki, z.B. Confluence. Mit CARDS+ versuchen wir, den Begriff Dokumentation weiter zu fassen. Nicht nur die Seiten im Wiki, sondern auch Code, Tests und Konfigurationen gelten als Dokumentation. Mit verschiedenen Ansätzen stellen wir Artefakte der Entwickler und Tester als lesbare Dokumentation zur Verfügung. Das Wiki bildet das zentrale Verzeichnis für die gesamte Dokumentation, mit Such- und Kommentarfunktion. Der Gärtner ist verantwortlich für die technische Infrastruktur des Wiki und Coach für Autoren und Leser.

Mit CARDS+ haben wir die “besseren Karten”.

In den Visionen versuche ich,  die Methode CARDS+ in unterschiedlichen Situationen anzuwenden. Die Visionen sind in vielen Fällen gedankliche Experimente. Trotzdem bin ich überzeugt, dass die hier beschriebenen Szenarien in der Realität funktionieren.

CARDS+ Produktionskette

Produktionskette

CARDS+ ist eine agile Methode mit dem Ziel, am Ende eines Produktinkrementes zusammen mit dem Software-Produkt eine vollständige und fehlerfreie Produktdokumentation bereitzustellen. Das Bild verwendet bewusst die Bildsprache von Scrum. Es geht hier aber nicht um Scrum, sondern um eine agile Methode zum Erstellen und Pflegen einer Produktdokumentation. In der Produktionskette von CARDS+ sehen wir, dass fünf Schritte  Priorisierung, Refinement, Planning, Realisierung und Review sich sehr schön mit einer auf Scrum basierten agilen Entwicklung synchronisieren lassen. Wir ergänzen die Produktionskette noch um drei Schritte für die agile Anforderungsanalyse: Bewertung, Validierung und Analyse einer Anforderung.

Ich durfte auch die Einführung der Methode CARDS+ in agilen Software-Projekten begleiten. Im Projektalltag führte ich oft sehr intensive Gespräche mit Kollegen. Diese Dialoge erfasse ich unter dem Titel “Redenswerte”.  In diesen teils kontrovers geführten Gesprächen entstehen immer wieder markante Aussagen, die einen Sachverhalt gut auf den Punkt bringen. Diese Zitate sammle ich unter dem Titel “Wissenswerte”.

Im Verlauf des Entwurfes der Methode CARDS+ habe ich eine ganze Reihe von Chancen, Risiken und Herausforderungen entdeckt und Lösungen und Empfehlungen im Rahmen der Methode entwickelt. In einer Reihe von Artikeln habe ich versucht, diese Erkenntnisse für mich und jeden interessierten Leser festzuhalten.

  1. Produktdokumentation
  2. Agile Methoden
  3. Zielgruppen
  4. Redundanzfreie Ablage
  5. Eindeutige Begriffe
  6. Vollständig dokumentieren
  7. Angemessen dokumentieren
  8. Nutzen
  9. Kosten
  10. Lösungsidee
  11. Backlog-Management
  12. Risiken
  13. Qualität

Das Ziel dieser Artikelserien besteht darin, den Problembereich Dokumentation in agilen Software-Projekten aus verschiedenen Blickwinkeln zu beleuchten und Hinweise zu geben, wie einzelne Probleme im Rahmen der Methode CARDS+ gelöst werden können.

ktip Eine druckbare Zusammenstellung aller Bausteine ist hier.
CARDS+ Prozessschritte

Prozesse und Bausteine

CARDS+ unterstützt iterative Prozesse in allen Bereichen eines Projekten mit seinen Bausteinen im Wiki. Die Unterstützung beginnt bereits bei der Vision des Produktes. Besondere Beachtung findet auch die Anforderungsanalyse, egal ob agil oder phasenorientiert. Die effiziente Nutzung in der agilen Entwicklung und dem Backlog-Management steht aber im Vordergrund. Der Entwurf aller Bausteine im Wiki folgt agilen Gedanken. Ein Baustein kann in der Regel innerhalb eines einzigen Prozessschrittes abgeschlossen werden, was im Bild links durch die ausgefüllten Kreise angedeutet wird. Nur in der Anforderungsanalyse bleiben die Bausteine Epic, Case und Service unvollständig. Der Grund ist klar: Erst durch die Realisierung können die letzten Fragen beantwortet werden.

Jeder Baustein ist prüfbar, weil er eine nachvollziehbare Struktur besitzt. Bausteine sind eindeutig einem Bereich der Produktdokumentation zugeordnet werden.

In der Systembeschreibung geht es konkret um den Versuch, das fachliche Produktwissen vollständig und widerspruchsfrei zu erfassen. Sie besteht aus der lückenlosen Dokumentation des Problemraumes, in dem sich die Nutzer des Systems bewegen, also aller Anwendungsfälle, Sonderfälle und Fehlerfälle der Funktionalität des Systems. Hier die alphabetisch geordnete Liste der Bausteine der Systembeschreibung:

Die Architekturdefinition besteht aus Bausteinen für die Dokumentation von Qualitätsmerkmalen, Entscheidungen und Konzepten. Sie bilden die Grundlage für die Implementierung. Hier die alphabetisch geordnete Liste der Bausteine der Architekturdefinition:

Mit der Systemstruktur verfolgen wir die Idee, den Aufbau eines Software-Produktes zu erfassen. Sie besteht aus der lückenlosen Dokumentation des Lösungsraumes, in dem sich die Entwickler des Systems bewegen, also Dienste und wichtige Objekte des Systems. Hier die alphabetisch geordnete Liste der Bausteine der Systemstruktur:

Die exakte Definition der Bausteine ist Autoren und Lesern gleichermaßen bekannt. Die Beschreibung der Bausteine stellt 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.

Die Initiative der «clean code developer» für mehr Professionalität in der Software-Entwicklung ist ein von mir persönlich geschätzter Katalog von Prinzipien und Praktiken, die uns zu professionelleren, besseren Entwicklern machen (sollen).

Ich behaupte, dass sich diese und viele andere Prinzipien der Entwickler ganz leicht auch auf das Dokumentieren in einem Wiki anwenden lassen. Diese Prinzipien und ihre praktische Umsetzung sind ein wichtiger Teil der Methode CARDS+.

Ein Metamodell in Form eines UML-Klassendiagrammes hilft, sich einen Überblick über die Struktur der Artefakte zu verschaffen. Die Artefakte selbst existieren

  • in einem Anforderungsmanagementsystem,
  • in einem Dokumentenmanagementsystem,
  • in einem Wiki (“Pages”),
  • in einer Vorgangsverwaltung  (“Issues”) oder
  • in einem Code-Repository.

Mit einer stark technischen Perspektive kann die Struktur der Dokumentation als UML-Klassendiagramm modelliert werden. Die Klassen sind die Bausteine der Methode CARDS+. Die Metamodelle verschaffen uns einen groben Überblick über die Zusammenhänge der Bausteine.  Sie erlauben aber auch eine Abgrenzung der Bausteine hinsichtlich ihrer Verwendung oder Zielgruppen.

Der Wert einer Methode zeigt sich erst im praktischen Einsatz. CARDS+ tritt an, die Qualität und Nutzbarkeit einer Produktdokumentation zu verbessern, in allen Prozessen der agilen Software-Entwicklung.

Das Wiki ist ein wesentlicher Bestandteil des Gesamtkonzeptes der Methode CARDS+. Es muss sehr sorgfältig gewählt werden. Die Methode stellt ganz konkrete Anforderungen an das Wiki. Auch die Nutzung der zentralen Funktionen eines Wiki – Seiten, Beiträge, Kommentare, Stichworte – ist ein wichtiger Faktor für die Qualität der Inhalte. Aber CARDS+ beschränkt stellenweise die Funktionen eines Wiki. Mit den Bausteinen gibt es eine feste Struktur, die für alle Autoren gilt. Die Idee der Medienbibliothek fordert eine zentrale Ablage für Abbildungen und Diagramme.

Weitere häufig gestellte Fragen sind:

Das Produkt Confluence vom australischen Hersteller Atlassian ist bekannt. Es erfüllt schon in der Grundversion ohne Erweiterungen (englisch: add-ons) alle Anforderungen von CARDS+ an ein Wiki.

Anforderungsanalyse (englisch: requirements engineering) ist hier ein zusammenfassender Begriff für alle strategischen bzw. operativen Tätigkeiten und Managementaufgaben, um nachvollziehbare Anforderungen für das Projekt zu erfassen und ausreichend genau zu beschreiben.

CARDS+ ist kein Ersatz für Methoden und Techniken der Anforderungsanalyse. Die Systembeschreibung ist keine Anforderungsdokumentation. Sie ist vielmehr die Interpretation der Anforderungen im Rahmen der Möglichkeiten des Produktes.

Ziel von CARDS+ ist es jedoch, die Ergebnisse der Anforderungsanalyse, d.h. die Bedürfnisse der Nutzer und die Erfordernisse in den Geschäftsprozessen des Unternehmens inkrementell und nachhaltig in der Systembeschreibung mit den Bausteinen Topic, Epic und Case zu erfassen. Fachliche Entscheidungen der Stakeholder werden bei Bedarf außerdem mit dem Baustein Decision dokumentiert.

Weitere häufig gestellte Fragen sind:

Die Dokumentation der Benutzeroberfläche gliedert sich in zwei Teilbereiche: In die Definition der Struktur der Benutzeroberfläche und auf das Benutzerhandbuch (englisch: users manual).

Die Benutzeroberfläche spezifizieren UX-Spezialisten mit verschiedener Ausprägungen des Bausteines Layout (englisch: user interface design), z.B. Fenster einer Desktop-Anwendung (Windows) oder einer Smartphone- oder Tablet-App (Screen). Die Zielgruppe sind Entwickler und Tester.

Das Benutzerhandbuch (englisch: users manual) schreiben in der Regel technische Redakteure. Sie nutzen dabei den Baustein Manual. Die Zielgruppe sind die Nutzer.

Weitere häufig gestellte Fragen sind:

Architekturdefinition (englisch: architecture specification) hat zum Ziel, alle fundamentalen Entscheidungen, die zu der vorliegenden Lösung geführt haben, mit dem Baustein Decision zu dokumentieren. Die Systemstruktur beschreiben wir mit den Bausteinen DomainServiceEntity und Event und vermitteln damit einen Überblick über die Größe und Komplexität des Systems.

Weitere häufig gestellte Fragen sind:

Komplexe IT-Systeme bestehen aus Software, Middleware und Hardware. Der Betrieb eines IT-Systems stellt nicht erst seit der Idee der DevOps eine große Herausforderung an eine Betriebsorganisation. Die Anforderungen an die Mitarbeiter sind dementsprechend hoch. Sie müssen mit der Vielzahl von Technologien umgehen können, häufig in einer produktspezifischen Art und Weise.

Mit Betriebsanweisungen und dem Baustein Task bekommt die Betriebsorganisation eine Dokumentation an die Hand, mit der sie der Herausforderung für den Betrieb eines IT-Systems begegnen kann.

Bei der Implementierung wird in der Regel nicht nur individueller Code geschrieben. Es gibt Abhängigkeiten zu Open-Source- oder kommerziellen Produkten. Als Modul hilft der Baustein Spec bei der Beschreibung von Bibliotheken, Infrastruktur oder Datenbanken.

Weitere häufig gestellte Fragen sind:

Es gibt aber eine klare Abgrenzung zur Projektdokumentation. Die Regeln sind einfach. In der Produktdokumentation wird Wissen erfasst, für das es einen Baustein gibt und das einen Zustand ist oder das Ergebnis eines Prozesses beschreibt. Alles andere gehört zur Projektdokumentation. Das bedeutet jedoch nicht, dass Projektdokumentation unwichtig ist. Im Gegenteil, es ist wertvoll, weil es gebraucht wird.  Es wird aber getrennt von der Produktdokumentation (z.B. Projekt- oder Teambereich) aufbewahrt und unterliegt nicht den Regeln von CARDS+.