Ein ganz wesentliches Ziel der Methode CARDS+ ist die Qualität der Inhalte. Prinzipien und Praktiken der Methode sollen unter anderem Autoren die Pflege einer Produktdokumentation im Wiki so einfach wie möglich machen. Die wohl wichtigsten Leitsätze sind:

  • Erfasse jede Information nur an einer Stelle im Wiki.
  • Erfasse nur jene Information, für die es Leser gibt.
  • Erfasse keine Information im Wiki, die an einer anderen Stelle bereits ausreichend beschrieben wurde.
  • Lass jede Änderung mindestens einmal prüfen.
  • Ignoriere keinen Fehler.

Beachten wir sie nicht, ist es sehr wahrscheinlich, dass Inhalte im Wiki sprichwörtlich verderben. Das Schlimme an den verdorbenen Dokumenten ist, dass wir sie niemals sofort erkennen.

Aufmerksamkeit

Anders formuliert benötigt eine Produktdokumentation ein gewisses Maß an dauerhafter Aufmerksamkeit. Es lebt vom Feedback der Leser. Berücksichtigen Autoren die Prinzipien der Methode CARDS+ und verwenden und trainieren ihre Praktiken, dann ist der Aufwand für die Erstellung einer Dokumentation nicht höher als bei anderen Methoden. Ich bin mir in diesem Punkt sehr sicher, weil wir Prinzipien und Praktiken anwenden, die beim Programmieren seit vielen Jahren für Entwickler sehr gut funktionieren und dort schon längst nicht mehr in Frage gestellt werden.

Der Gärtner als Verwalter im Wiki sorgt dafür, dass auch jene Dokumentation gepflegt wird, für die es gerade keinen Autor gibt. Er achtet auch darauf, dass keine Alibi-Dokumentation, also keine Dokumentation erstellt wird, die nur der Erfüllung formaler Richtlinien dient, aber keine Leser hat. Lässt sich aus rechtlichen oder anderen wichtigen Gründen eine formale Dokumentation nicht vermeiden, dann findet der Gärtner einen Weg, sie mit wenig Aufwand zu erstellen. Oder er findet sogar einen Weg, wie so eine Dokumentation aus dem Wiki heraus exportiert wird.

ktip In Confluence reicht die Standardfunktion leider nicht für einen professionellen Export aus dem Wiki. Die Erweiterung (Add-onScroll-Office schafft hier Abhilfe.

Rechtzeitigkeit

Die Methode CARDS+ ist so gestaltet, dass Autoren Dokumentation inkrementell erstellen. Wissen erfassen sie in dem Umfang, der zum gegebenen Zeitpunkt vorliegt. Nicht mehr, nicht weniger. Und Wissen sichern sie rechtzeitig, wenn es noch frisch ist.

Rechtzeitig bedeutet auch, dass Product-Owner die Dokumentation in Workshops mit den Stakeholdern oder seinem Team benutzt. Durch das Wiki und die Kommentarfunktion ist es leicht, Veränderungen, Erkenntnisse oder Annahmen während des Workshops für alle Beteiligten sichtbar zu machen (z.B. Beamer) und offene Punkte in einer für alle verständlichen Form gemeinsam zu formulieren. Im Anschluss kann ein Product-Owner oder Business-Analyst die Ergebnisse sichten, bewerten und an der richtigen Stelle im Wiki einfügen. Die Kommentare werden dann im nächsten Workshop für alle sichtbar gelöscht, wenn alle den Änderungen zustimmen (moderierte Kommentare).

Angemessenheit

Manches Wissen mag für den Moment ganz wichtig erscheinen. Autoren dürfen bei der Beurteilung der Angemessenheit aber nie vergessen, dass Wissen vor allem im Produkt selbst steckt. Wissen wird durch die Software-Entwicklung in Code und Tests transformiert.

Wenn ein Product-Owner zu Beginn eines Sprints zu detailliert im Wiki dokumentiert, dann passiert es sehr leicht, dass er am Ende des Sprints zu viel dokumentiert hat. Die Lösung für dieses Dilemma klingt ganz simpel. Im Wiki beschränkt er sich auf Antworten auf die Fragen

  • Was ist das Problem?
  • Wer sind die Nutzer?
  • Wieso brauchen sie eine Lösung?
  • Wann nutzen sie das Produkt?

Bei der Frage nach dem Wie ist er vorsichtiger. Ideen und Annahmen formuliert er besser in den Gesprächen mit den Entwicklern oder – wenn es schriftlich gefordert wird – als Beschreibung in den Stories im Sprint-Backlog. Gerade bei der Nutzung des Bausteins Case bleibt er im Zweifelsfall lösungsoffen. Erst am Ende des Sprints, im Review, lernt er die richtige Lösung kennen. Das ist der Zeitpunkt, die Lösung angemessen zu beschreiben.

Das gleiche gilt natürlich auch für die Bausteine Domain, Service, Event und Entity. Dort sichern Entwickler Wissen über die technische Lösung, das schwer oder gar nicht durch Code vermittelt wird. Also alles, was sie nur durch einen Code-Kommentar erklären können: Ein Workaround, weil ein API einen Bug hat oder eine nicht offensichtliche Optimierung.

Fazit

Viele Ideen und Vorschläge der Methode CARDS+ haben das Ziel, den Umfang der Dokumentation zu minimieren. Ganz dem Motto des agilen Manifests folgend ist uns das Produkt sehr wichtig und wir wollen eine angemessene Dokumentation. Wir definieren Qualität an Kriterien wie Vollständigkeit und Richtigkeit. Wir können durch moderierte Kommentare eine Metrik für die Dokumentation schaffen. Durch die feste Struktur der Bausteine haben wir die Möglichkeit einer formalen Prüfung der Inhalte. Aber wir besitzen kein Werkzeug, mit dem wir Dokumentation messen können. Qualität ist das Ergebnis der Anstrengungen eines ganzen Teams. Es ist Kopfsache.