cards+ unterstützt eine Projektorganisation, Wissensmanagement in einem agilen Entwicklungsprojekt richtig zu organisieren. cards+ tritt mit dem Versprechen an, die Erstellung und langfristige Pflege einer hochwertigen und hilfreichen Produktdokumentation in einem Wiki zu ermöglichen. Viele Prinzipien und Praktiken der Entwickler gelten auch für Autoren in einem Wiki.
cards+ unterstützt eine Projektorganisation, Wissensmanagement in einem agilen Entwicklungsprojekt richtig zu organisieren. Der Produktverantwortliche setzt cards+ ein, um zielgerichtet und inkrementell sein Produkt angemessen zu dokumentieren, unterstützt durch ein selbstorganisiertes Team.
Es gilt die Prämisse, dass eine angemessene Produktdokumentation notwendig ist. Eine solche Produktdokumentation wächst mit dem Produkt. Sie ist ein Ergebnis des agilen Entwicklungsprozesses. Sie muss daher mit dem gleichen Maßstab für die Qualität, mit dem gleichen Ansatz für empirische, inkrementelle und iterative Arbeitsweise und mit den gleichen Werten hergestellt wird, wie auch das Produkt entwickelt wird. An diesem Punkt kommt die Methode cards+ ins Spiel.
Dokumente werden agil entwickelt.
cards+ tritt mit dem Versprechen an, die Erstellung und Pflege einer qualitativ hochwertigen Produktdokumentation in einem Wiki zu ermöglichen. Viele Prinzipien und Praktiken der Entwickler gelten auch für Autoren in einem Wiki, in den meisten Fällen in nur leicht abgewandelter Form.
cards+ ist kein geschlossenes Vorgehensmodell, kein isolierter Prozess. Aus diesem Grund kann cards+ sehr gut in bestehende Prozesse integriert werden. Autoren im Wiki planen und steuern ihre Tätigkeiten weiterhin mit Techniken aus dem Projektmanagement. Sie verwenden die Methode ihrer Wahl für die Anforderungsanalyse. cards+ ist als zusätzliches Werkzeug für Autoren zu verstehen, mit dem sie ihre Ergebnisse im Wiki organisieren.
Für Leser ist cards+ die Chance, im Wiki jede relevante dokumentierte Information zum Produkt zu finden. Das Wiki unterstützt sie durch die Verknüpfung von Seiten, die Kategorisierung der Seiten mit Stichworten und umfangreiche Suchfunktionen.
Dokumente agil entwickeln.
Visualisierung hilft, komplexe Zusammenhänge zu verdeutlichen. Durch gut gemachte Bilder wird die Aufmerksamkeit der Leser deutlich erhöht. Es entsteht eine gemeinsame Sprache: Die Bildsprache. Wichtige Begriffe werden sichtbar. Sie bekommen ein «icon» mit hohem Wiedererkennungswert. Der Komponentenüberblick gibt — wie der Name schon sagt — einen Überblick über die Komponenten des IT-Systems. Die Abbildung zeigt abstrakt Dienste und Datenflüsse und zieht Grenzen. Hier wird deutlich, dass cards+ und Domain-Driven Design (kurz DDD) sehr ähnliche Ansätze verfolgen.
Das wichtigste Element im strategischen Design von DDD ist die Kontextgrenze (engl. bounded context), rein formell eine Gültigkeitsgrenze für ein fachliches Modell einer Domäne. Domänen unterscheiden sich in ihrer Relevanz für den Erfolg des IT-Systems. DDD unterscheidet wichtige Domänen (engl. core domains), die den Unterscheid machen, und unterstützende Domänen (engl. generic domains), für die es häufig Standardlösungen gibt. Die Kontextlandkarte (engl. context map) ist eine abstrakte Sicht auf alle Domänen des IT-Systems. Wechselwirkungen und die Einflussnahme von Domänen untereinander werden durch eine Reihe von Interaktionsarten dokumentiert. Im taktischen Design von DDD gibt es die Grundelemente Service, Event, Entity und Value. Für die Modellierung komplexer Datenstrukturen gibt es das Element Aggregate.
cards+ erfindet DDD nicht neu. cards+ ist ein Angebot, ein agiler Ansatz, um die Ergebnisse der Modellierung aus dem DDD in einem Wiki zu sichern. Im strategischen Design kann der Komponentenüberblick von cards+ mit der Kontextlandkarte von DDD gleichgesetzt werden. Kontextgrenzen werden durch den Baustein Domain repräsentiert. Im taktischen Design mit DDD ist cards+ eine optimale Ergänzung. DDD legt dabei das Vorgehen bei der Analyse fest. Für die Beschreibung der Ergebnisse gibt es passende Bausteine bei cards+. Der Baustein Entity wird für die Elemente Value, Aggregate und Entity verwendet. Für die Elemente Service und Event gibt es die gleichnamigen Bausteine Service und Event.
Dokumentieren ist ein erlernbares Handwerk. Prinzipien der Methode cards+ unterstützen die Autoren dabei. Ihre praktische Umsetzung ist ein wichtiger Teil der Methode.
Scrum oder XP haben die Arbeitsweise der Entwickler nachhaltig verändert. Die Initiative der «clean code developer» beinhaltet einen Katalog von Prinzipien und Praktiken für mehr Professionalität in der Software-Entwicklung. Als Hilfestellung bekommen Entwickler ein Wertesystem, an dem sie sich orientieren können. Das gilt auch für das Dokumentieren im Wiki. Die gleichen Prinzipien machen auch die Arbeit von Autoren besser.
«Convention over documentation» hat das Ziel, Dokumentation durch Konventionen zu vermeiden oder zu reduzieren.
«Convention over documentation» hat das Ziel, Dokumentation durch Konventionen zu vermeiden oder zu reduzieren.
Eine «Definition of done» verkörpert ein explizites und geteiltes Verständnis davon, unter welchen Bedingungen ein Produkt fertig ist.
«Don´t repeat yourself» hat zum Ziel, jede unnötige Wiederholungen von Inhalten im Wiki zu vermeiden.
«Invest in good stories» definiert sechs Kriterien, die uns helfen, fachliches Wissen so kompakt und vollständig wie möglich zu vermitteln.
«Keep it simple, stupid» besagt, dass wir eine möglichst einfache Beschreibung für Inhalte wählen sollen. «Weniger ist mehr» sagt schon ein Sprichwort. Einfachheit ist die Kunst, die Menge nicht getaner Arbeit zu maximieren.
«Principle of least astonishment» spiegelt sich im Aufbau der Seiten im Wiki wider. Jeder Baustein hat genau einen Zweck, festgelegte Abschnitte und ist das Ergebnis eines bestimmten Prozesses.
«Single level of abstraction» spiegelt sich in der Struktur des Wiki wider. Für jede Seite ist klar definiert, was in einer Seite beschrieben wird und was nicht in diese Seite gehört.
«Separation of concerns» führt dort zu einer Trennung fachlicher und technischer Dokumentation, wo es Sinn macht.
«Single responsibility principle» regelt die Verantwortung für den Inhalt im Wiki. Eine Seite hat immer genau einen Autor. Er ist für den Inhalt der Seite verantwortlich, bis sie «fertig» ist.
Jede an einem IT-System interessierte Partei hat ihre eigene Vorstellung von guter Dokumentation. Diese Vorstellung ist ganz maßgeblich von ihren persönlichen Schwerpunkten bestimmt. «Viele Köche verderben den Brei» ist ein Sprichwort, das wahr wird, wenn jede an der Produktdokumentation beteiligte Person so schreibt, wie sie es aus persönlicher Sicht für richtig hält. Leser und Autoren brauchen ein Grundgerüst, an dem sie sich orientieren können. cards+ bietet dafür die feste Struktur mit den Bereichen Systembeschreibung, Systemstruktur und Architekurentwurf. In jedem Bereich gibt es vordefinierte Bausteine mit festem Aufbau.
cards+ unterscheidet drei Rollen, die wesentlich zum Gelingen einer Produktdokumentation beitragen: Leser, Autoren und Gärtner. Aufgrund der Trennung von Dokumentation im Wiki und Spezifikation durch das Team im Code-Repository bezieht sich die Definiton der Rollen von cards+ nur auf die Personen, die direkt im Wiki arbeiten.
Alle Gärtner und Vertreter der Autoren sind Teil einer Expertenrunde (engl. community of practice) und Sprecher der Zielgruppen der Produktdokumentation.
Leser ist jede am Produkt interessierte Partei. Ein Leser nutzt das Wiki als Hilfsmittel zur Erfüllung seiner Aufgaben im agilen Entwicklungsprozess. Das Wiki ist für ihn eine unverzichtbare Quelle für Produktwissen. Jeder Leser ist berechtigt, im Wiki Seiten zu lesen und zu kommentieren.
Produktverantwortliche, Analysten, IT- und UX-Experten, Redakteure und Vertreter des Realisierungsteams sind Autoren. Interessierte Parteien unterstützen sie als Co-Autoren. Ein Autor ist berechtigt, neue Seiten im Wiki anzulegen und bestehende Seiten zu ändern oder zu löschen. Seine Aufgabe ist es, Seiten im Wiki inkrementell mit Produktwissen zu füllen.
Gärtner sind Experten für Dokumentation und Administrator für das Wiki. Sie sind verantwortlich für die Auswahl der Werkzeuge für die Erstellung der Dokumentation. Als Trainer für cards+ ist er für Autoren und Leser greifbar und hilft ihnen bei der Bewältigung von alltäglichen wie auch speziellen Problemen im Zusammenhang mit Dokumentation.
Kommentare im Wiki erfolgreich moderieren.
Wie beim Programmieren gehört die Anwendung der Pfadfinderregel auch beim Dokumentieren zum Fundament professioneller Arbeit. Leser können jederzeit einen entsprechenden Hinweis als Kommentar in der Seite hinterlassen. Autoren greifen diese Hinweise wertschätzend auf. Nach dem Abschluss der Verbesserung wird der Kommentar gelöscht.
Jeder Autor im Wiki kann bereits beim aktiven lesen einer beliebigen Seite kleine, aber wichtige Korrekturen durchführen. Kleine Korrekturen sind beispielsweise die Verbesserung von Rechtschreibfehlern oder die Verknüpfung von Begriffen im Text mit Einträgen im Glossar. Durch diese ebenfalls recht einfache Maßnahme erkennt der Autor automatisch wiederholt auftretende Erklärungen im Text, die er ohne Verlust von Wissen aus der Seite entfernen kann. Gegebenenfalls ergänzt er Schlagworte in der Seite. Schlagworte sind Begriffe aus einem kontrollierten Vokabular. Bei cards+ wird dieses Vokabular durch das Glossar definiert. Mit dieser Maßnahme wird die Suche im Wiki für Leser deutlich verbessert.
Code-Reviews sind beim Programmieren nicht mehr wegzudenken. Das Vorgehen eignet sich nicht nur dazu, die Qualität der Software zu verbessern. Es unterstützt auch den Wissenstransfer innerhalb des Teams. Das Gesagte gilt auch für das Dokumentieren mit cards+. Bei der Durchführung eines Reviews einer Seite im Wiki prüft der Reviewer sowohl die Richtigkeit als auch die Vollständigkeit der Inhalte.
Die Richtigkeit der Seite schätzt der Reviewer anhand seines eigenen Wissens ein. Die Verknüpfung von Begriffen im Text mit Einträgen im Glossar unterstützt ihn dabei. Beim Lesen korrigiert er offensichtliche Fehler in der Rechtschreibung. Der Editor des Wiki hilft dabei. Bei allen anderen Fehlern oder Lücken nutzt er die Kommentarfunktion, um Hinweise für den Autor in der Seite zu hinterlassen.
Eine Seite ist vollständig, wenn
- die vorbereitete Seitenvorlage des Bausteins verwendet wurde.
- alle Abschnitte aus der Seitenvorlage des Bausteins ausgefüllt sind.
- passende Schlagworte in der Seite gesetzt sind.
Diese rein formalen Prüfungen sind möglich, weil die Seitenvorlagen einen festen Rahmen für jeden Baustein vorgeben.
Ein Wiki ist optimal geeignet für die Erfassung, Pflege und vor allem Präsentation von Produktwissen. Die Pflege von Seiten direkt im Wiki kommt dort an seine Grenzen, wo regelmäßig und in kurzen Abständen Veränderungen gemacht werden. Das ist vor allem dort der Fall, wo eine Lösung für eine Fähigkeit der Software von den Entwicklern sehr genau beschrieben wird. Diese Art dokumentierter Informationen sind ganz eng an die Implementierung gekoppelt und werden in der Konsequenz zusammen mit dem Code versioniert.
In einer Spezifikation halten Entwickler die Struktur eines Objektes, Geschäftsregeln und Algorithmen eines Dienstes oder den Aufbau und das Verhalten einer Bedienoberfläche fest. cards+ macht keine Vorgaben für eine Spezifikation. Mit der Freigabe der Software für das Produktinkrement wird jede damit verbundene Spezifikation im Wiki in den Bausteinen Service, Entity, Event oder Layout veröffentlicht.
Eine ähnliche Situation gibt es bei den Testplänen in einer Testpyramide. Die Testfälle eines Systemtests sind sehr gut als zusätzliche Dokumentation geeignet, wenn sie sich an den Fähigkeiten der Software orientieren. cards+ macht keine Vorgaben für einen Testplan. Mit der Freigabe der Software für das Produktinkrement werden die durchgeführten Testfälle im Wiki veröffentlicht. Abhängig vom Aufbau der Testpläne bieten sich die Bausteine Epic oder Case an.
Sowohl Spezifikationen als auch Testpläne sind wie Code Teil des Produktinkrementes und damit ein Ergebnis des Teams. Es ist Aufgabe des Teams, für die dokumentierten Informationen ein geeignetes Format zu wählen, das im Wiki veröffentlicht werden kann. Am besten automatisierbar.
Der Produktverantwortliche hat eine Vision des Produktes. Den Baustein Epic gibt einer angeforderten Funktionalität des Produktes einen eindeutigen Namen und gruppiert die neuen Fähigkeiten der Software. Den Baustein Case legt er an, um jeder neuen Fähigkeit der Software einen Titel zu geben und die Ausgangslage kurz zu beschreiben. Die Lösung bleibt auf jeden Fall offen. Kann der Produktverantwortliche mit seiner Vision einen Auftraggeber begeistern, bekommt er häufig die Frage gestellt, was das den ungefähr kostet. Agil hin oder her, er braucht eine realistische Zahl, an die er selbst glaubt. Für eine Expertenschätzung durch sein Team muss er sehr viel Arbeit in das Backlog investieren. Und selbst dann ist die Schätzung in der Regel mit einer hohen Ungenauigkeit verbunden.
cards+ eröffnet eine neue Option mit dem Einsatz der Schätzmethode «Use-Case-Points» von Stephan Frohnhoff. Der Baustein Case erfüllt alle Bedingungen als Eingangsgröße für die Schätzmethode. Jeder Case wird auf einer Skala von einfach, normal oder komplex mit Punkten bewertet. Die Punkte aller Fähigkeiten der Software werden addiert und mit Faktoren gewichtet. Es gibt Faktoren für technische Komplexität, das Projektumfeld und die Produktivität des Teams. Das Ergebnis sind Personenstunden. Der geschätzte Wert ist natürlich mit einer Ungenauigkeit verbunden. Mit der Realisierung von Fähigkeiten kann die Schätzung kalibriert werden.
Der Produktverantwortliche wird in die Lage versetzt, die die Schätzung kontinuierlich zu aktualisieren. Fügt er einen neuen Baustein Case hinzu, ergänzt er die Schätzung um eine Bewertung der neuen Fähigkeit der Software. Er orientiert sich dabei an den bereits vorhandenen Fähigkeiten. Der Auftraggeber bekommt in sehr kurzer Zeit eine erste grobe Indikation der Kosten für die Realisierung.
Dokumentation nachhaltig organisieren.
Die Werte aus dem «Manifest für agile Software-Entwicklung» bilden das Fundament agiler Entwicklung. Mit cards+ kann auch Produktdokumentation agil entwickelt werden. Agil Dokumentieren bezeichnet ein schrittweises Erfassen von Entscheidungen und Wissen in einem agilen Entwicklungsprozess. Die Struktur der Produktdokumentation ist so gestaltet, dass Ergebnisse schrittweise mit einem geeigneten Baustein gesichert werden kann. Autoren schreiben nur das auf, was sie jetzt wissen. Keine Wünsche. Keine Vermutungen.
Aufgrund der maßgeschneiderten Struktur können Autoren trotzdem jeden Baustein in kurzer Zeit abschließen. Eine wichtige Bedingung für ein agiles Entwicklungsprojekt, um Dokumentation als ein weiteres Ergebnis einer Iteration zu fordern. In einem agilen Entwicklungsprozesses nutzt ein Produktverantwortlicher die Regeltermine, um Feedback auch zur Produktdokumentation einzusammeln. Mit dem Einsatz von cards+ gilt:
Dokumentation wird wie Code entwickelt!
Eine Produktdokumentation hat eine innere Struktur. Sie besteht aus Bausteinen mit einem klar formulierten und prüfbaren Inhalt. Es bietet sich ganz einfach an, die Produktdokumentation im gleichen agilen Prozess zu schreiben, in dem auch das Produkt programmiert und getestet wird. Sie hat das Ziel, den Zustand eines Produktinkrementes so exakt wie möglich zu beschreiben. Sie existiert im Wiki und wird genutzt, um Spezifikationen und Testpläne zu veröffentlichen. Sie bildet das zentrale Verzeichnis der für das Produkt relevanten Dokumente.
Eine Produktdokumentation 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. Testpläne, organisiert in einer Testpyramide, sichern die Qualität der Software ab. Handbücher geben Einblick in die Fähigkeiten der Software, erklären den Nutzern, wie sie verwendet werden. In den Bausteinen der Systembeschreibung wird der Problemraum des Produktes beschrieben. Sie geben Antwort auf die Fragen wer, wann und warum etwas mit dem Produkt tut. Die Bausteine der Systembeschreibung beantworten hingegen die Frage, wie das Produkt realisiert wurde. Zusammen mit den Bausteinen des Architekturentwurfs beschreiben sie den Lösungsraum.
Eine einigermaße komplexe Software ohne Dokumentation ist für mich nicht vorstellbar. Ein Produktverantwortlicher kann oder besser muss sich über den Prozess der Erstellung einer Produktdokumentation Gedanken machen. Im allgemeinen Sprachgebrauch werden Dokumente geschrieben. Mit cards+ werden Dokumente entwickelt. Das geht aber nicht mit jeder Art von Dokument.
Eine Produktdokumentation ist unverzichtbar für das Aufrechterhalten des agilen Entwicklungsprozesses und unterstützt die Kommunikation in der Projektorganisation. Sie beschreibt Ergebnisse. Abstimmungen führen zu Entscheidungen. Anforderungen werden analysiert und umgesetzt oder abgelehnt. Aufgaben werden erledigt, damit ein neues Produktinkrement entsteht.
Der Begriff Produktdokumentation fasst jene dokumentierte Informationen zusammen, die für das Aufrechterhalten von Prozessen, also Planung und Steuerung von Aufgaben, notwendig sind. cards+ bietet für die Projektdokumentation keinen Baustein! Die Artenvielfalt ist einfach zu groß. Die Bedürfnisse der interessierten Parteien sind zu unterschiedlich. Die Lebensdauer der Dokumente ist oft zu gering für einen wirtschaftlich vertretbaren Ansatz zur Standardisierung.
Für die Erfassung und Steuerung von Aufgaben in einem Backlog bietet cards+ keinen Baustein an. Mit den Bausteinen von cards+ wird jedoch wichtiges Wissen für eine Aufgabe rechtzeitig und strukturiert in der Produktdokumentation vorbereitet.
Die Verwaltung und Bewertung einer Anforderung ist nicht Teil der Methode cards+. Das Ergebnis der Anforderungsanalyse wird jedoch mit den Bausteinen Topic, Epic und Case angemessen in der Produktdokumentation dokumentiert.
Im Projektalltag finden laufend Abstimmungen statt. Jede Abstimmung mit großer Tragweite führt zu einer begründeten Entscheidung, die es wert ist, nachhaltig dokumentiert zu werden. cards+ bietet dafür den Baustein Decision an.
Eine Richtlinie ist eine Vereinbarungen, die die Zusammenarbeit im Entwicklungsprojekten und in den Teams regelt. Ist die Richtlinie relevant für das Produkt, kann sie natürlich mit den Baustein Concept für Konzepte in die Produktdokumentation aufgenommen werden.
In der agilen Welt ungeliebt, aber häufig notwendig, um ein Gewerk zu präzisieren und einen Vertrag zu schließen. Mit cards+ erstellen wir inkrementell eine Systembeschreibung mit den Bausteinen Topic, Epic und Case. Die gleichen Bausteine können wir als Lastenheft aus dem Wiki exportieren. Jederzeit.
Schätzen ist ein sehr häufig sehr kontrovers diskutiertes Thema in Entwicklungsprojekten, besonders in agilen. Der Baustein Case ist eine geeignete Basis für die Schätzmethode «Use-Case-Points» von Stephan Frohnhoff. Sie lässt sich praktisch direkt einsetzen.
Die Methode cards+ verfolgt ein sehr wichtiges Ziel: Eine lebendige Produktdokumentation. Sie lebt u.a. durch das Feedback der Leser. Feedback als Kommentare in den Seiten im Wiki ist für alle sichtbar, auch eventuell daraus entstehende Diskussionen.
Feedback ist im Wiki jederzeit willkommen.
Die Erstellung und Pflege von Inhalten im Wiki ist Aufgabe der Autoren. Dazu trägt ganz wesentlich die wertschätzende Verwendung des Feedbacks der Leser bei. Im Sinne der Nachhaltigkeit moderiert der Autor die Kommentare, d.h. er entfernt jene Kommentare, die bereits zur Korrektur der Dokumentation verwendet wurden. Nicht mehr relevante oder sachlich nicht korrekte Kommentare löscht er nach Abschluss der Klärung mit dem Ersteller des Kommentars. Durch dieses aktive Management der Kommentare schaffen wir Transparenz bei den Änderungen der Inhalte. Autoren können Kommentare auch als Indikator für die Qualität der Dokumentation heranziehen. Eine Seite im Wiki ohne Kommentare ist eine gute Seite. Andererseits ist eine Seite im Wiki mit Kommentaren schlicht und einfach nicht fertig. Sehr viele Kommentare aus einer von mehreren Lesern kontrovers geführten Diskussion sind ein klares Indiz für den Autor, das Thema der Seite noch einmal intensiver zu betrachten.
Leser nutzen einen Textkommentar, um eine redaktionellen Verbesserung zu melden. Dazu zählen Rechtschreib- oder Grammatikfehler in einem Text. Auch eine fehlende Verknüpfung eines Begriffes im Text mit einer Seite im Glossar ist hier gemeint. Die Korrektur der Seite kann ein Autor jederzeit und ohne umfangreiche Abstimmung durchführen.
Eine interessierte Partei (z.B. ein Nutzer) findet als Leser eine Lücke in einer Beschreibung und meldet sie mit einem Seitenkommentar. Bei einer Lücke reden wir nicht von einem Fehler. Trotzdem ist jeder Hinweis sehr willkommen, wenn er einem Autor hilft, die Beschreibung besser zu machen. Die Korrektur der Seite kann ein Autor jederzeit nach erfolgreicher Prüfung durchführen.
Eine interessierte Partei (z.B. ein Entwickler) hat als Leser den Eindruck, dass eine Beschreibung nicht vollständig ist. Solche Unklarheiten bezeichnen wir als offene Punkte, bis sie geklärt sind. Offene Punkte versucht der Autor der Seite so rasch wie möglich zu klären. Das Ergebnis der Klärung nutzt der Autor, um den Inhalt der Seite zu verbessern.
Eine interessierte Partei (z.B. ein Entwickler) hat als Leser den Eindruck, dass eine Beschreibung offensichtlich fehlerhaft ist. Die Einschätzung ist subjektiv, bedeutet aber, dass die kommentierte Seite nicht mehr fertig ist. Fehler muss der Autor der Seite so rasch wie möglich klären. Das Ergebnis der Klärung nutzt der Autor, um den Inhalt der Seite zu verbessern.
Es gibt das Phänomen, dass intelligente Menschen gegen Regeln verstoßen, obwohl sie von ihrer Wirksamkeit im Allgemeinen überzeugt sind. Trotzdem verteidigen sie die Abweichung von der Regel mit dem Argument, dass es eine notwendige Verbesserung oder gar Innovation ist. Manche tun es sogar im guten Glauben, dass ihr Weg besser ist, diese Änderung schon lange notwendig war. Das ist eine Gefahr für die Qualität einer Produktdokumentation. Individuell gestaltete Seiten sind praktisch nicht prüfbar. Es ist schwerer, die Bearbeitung einer Seite an einen anderen Autor zu übergeben. Die Bausteine bilden ein abgestimmtes Konzept. Abweichungen gefährden die Konsistenz. Abgrenzung ist eine hilfreiche Methode, um diesem Problem zu begegnen.
Die Goldene Regel der Gärtner besagt, dass eine Information, für die es keinen Baustein in der Produktdokumentation gibt, ganz automatisch zur Projektdokumentation gehört — und damit anderen Regeln unterliegt. Das hat natürlich Konsequenzen bezüglich Nachhaltigkeit und Qualität. Eine Herausforderung für einen Gärtner ist, Stärke zu zeigen. Stärke, Autoren auf die Einhaltung der Regeln der Produktdokumentation einzuschwören.
Der Gärtner ist verantwortlich für die Auswahl der Werkzeuge und der technischen Infrastruktur für das Wiki. Das ist sozusagen die Entwicklungsumgebung für die die Autoren. Er ist Experte im Zusammenhang mit Dokumentation. Seine Aufgaben sind die Formulierung und Durchsetzung von Dokumentationsrichtlinien, ähnlich den Programmierrichtlinien der Entwickler. Er sorgt für die Einhaltung der Regeln der Methode cards+, vergleichbar dem Scrum-Master als Hüter des Scrum-Prozesses oder einem IT-Experten für den Architekturstil. Aus dieser Argumentation heraus ergibt sich zwangsläufig, dass für die Pflege einer Produktdokumentation ein Gärtner in der Art eines IT-Experten für Dokumentation gebraucht wird.
Der Gärtner ist Trainer für die Methode cards+. Er ist greifbar für Autoren und Leser und hilft bei der Bewältigung von alltäglichen wie auch speziellen Problemen im Zusammenhang mit der Dokumentation. Ähnlich wie beim Verhältnis von IT-Experte und Entwickler (Stichwort Elfenbeinturmarchitekt) ist es für einen Gärtner sehr hilfreich, selbst auch Autor zu sein. Zumindest muss er aktiver Leser sein.
Robert Bruckbauer beantwortet Fragen und unterstützt als Gärtner.
Eine große Gefahr für die Leistungsfähigkeit eines Teams sind Kopfmonopole und Wissensinseln. Eine Person sammelt über lange Zeit wertvolles Wissen über das Produkt. Sie nutzt dieses Wissen, um erfolgreich Aufgaben im Team zu erfüllen. Dann verlässt sie das Team. Wichtiges. Nicht schriftlich erfasstes Wissen geht unwiderbringlich verloren. Selbst bei einem gut vorbereiteten Ausstieg mit Übergabe oder einer schriftlichen Nachdokumentation gehen Informationen verloren.
Ein Grund für Wissensverfall ist die Trägheit des menschlichen Gehirns und das damit verbundene Vergessen von Informationen. Ein Mensch erinnert sich gut an die aktuellen Aufgaben. Aber an alle länger zurückliegenden, in der Regel abgeschlossene Aufgaben kann er sich weniger gut erinnern. Wichtige Details bleiben unerwähnt.
Die Vergemeinschaftung von Wissen (engl. shared knowledge) ist eine Maßnahme, die diesem Verfall entgegenwirkt. Jeder im Team teilt sofort sein Wissen. Er tut dies nachhaltig, also schriftlich. Mit cards+ ist das Erfassen sehr einfach. Durch das Wiki gibt es keine Hürden. Internet und ein Browser reicht.
Das «Manifest für agile Software-Entwicklung» verlangt nicht den Verzicht auf Dokumentation, sondern will, dass das eigentliche Ziel, ein funktionierendes Produkt, nicht darunter leidet. Dokumentieren im Allgemeinen wird trotzdem von so manchem Entwickler als Aufgabe abgelehnt. Sie wollen nur das dokumentieren, was für ihre Arbeit als Entwickler oder Tester einen Wert darstellt. Dokumentieren wird in besonderen Situationen gerne auch auf später verschoben. Andere Entwickler dokumentieren in der “heißen” Phase der Realisierung sehr gerne und ausgiebig ihre aktuelle Lösung. Es entstehen sehr genaue Beschreibungen und detailgetreue Bilder. Sobald aber die Software eine gewisse Reife erreicht, sinkt die Motivation, diese Dokumente zu aktualiseren.
Beide Vorgehensweisen führen zu fachlichen Schulden. Das Produkt ist unvollständig. Die Produktdokumentation enthält sprichwörtlich «verdorbene» Dokumente. Leider können Leser die «faulen» Stellen in der Dokumentation nicht immer erkennen. Sie werden in die Irre geführt und verlieren das Vertrauen in die Dokumentation. Damit beginnt ein Teufelskreis. Weniger Leser bedeutet weniger Feedback für die Autoren. Fehlendes Feedback führt zu sinkender Qualität. Sinkende Qualität vertreibt weitere Leser.
Mit cards+ wird mit den Begriffen Systembeschreibung, Systemstruktur, Spezifikation und Testplan eine klare Aufgabenteilung zwischen Produktverantwortlichen und seinem Team angestrebt.
Der Produktverantwortliche bewegt sich im Wiki. Er nutzt die Bausteine der Systembeschreibung, um seine Vision bis hinunter zu einer konkreten Fähigkeit der Software zu dokumentieren. Er nutzt die Bausteine der Systemstruktur, um Diensten und Objekten in Abstimmung mit dem Team eindeutige Namen und einen fachlichen Zweck zu geben. Für jede geforderte Fähigkeit schreibt er einen Arbeitsauftrag (engl. story) für die Entwickler. Dort konkretisiert er einen unvollständigen Baustein Case durch Akzeptanzkriterien. Unvollständig heißt in diesem Fall ohne Lösung.
Das Team nimmt entsprechend der Priorisierung des Produktverantwortlichen einen Arbeitsauftrag an. Es ist vollkommen unstrittig, dass Programmieren und Testen beides Aufgaben des Teams sind. Sie suchen eine Lösung für die geforderte Fähigkeit der Software im Rahmen des gewählten Architekturstils. Die Akzeptanzkriterien im Arbeitsauftrag sind Grundlage für die Testpläne. Die Ergebnisse des agilen Entwicklungsprozesses, also Code, code-nahe Artefakte, Testpläne und Spezifikationen, werden in einer quelltext-basierten Versionsverwaltung nachvollziehbar gespeichert.
In der Methodik von cards+ ergeben die Bausteine im Wiki als auch die Ergebnisdokumente der Entwickler und Tester zusammen eine vollständige Produktdokumentation. Eine Dokumentation wirkt aber nur dann vollständig, wenn alle dokumentierten Informationen in einem Medium präsentiert wird. Das ist im Fall von cards+ das Wiki. Dort befinden sich bereits die Bausteine. Durch geeignete Konvertierung werden Spezifikationen der Entwickler und Testpläne der Tester im Wiki veröffentlicht.