Agile Entwicklung mit Scrum hat aus gutem Grund Regeln, die alle einzuhalten sind. Scrum ist es nur, wenn die drei Rollen Product-Owner, Scrum-Master und Team besetzt sind, das Team in regelmäßigen Sprints ein Product-Backlog abarbeitet und kontinuierlich Produktinkremente liefert. Jeder Sprint wird gemeinsam geplant (Refinement, Planning). Am Ende jedes Sprints gibt es eine Präsentation der Sprint-Ergebnisse (Review). Nur so funktioniert Scrum. Eine Vereinfachung (z.B. Weekly statt Daily) birgt das Risiko, dass das Vorgehen nicht mehr die gewünschten Ergebnisse liefert. Jede grundsätzliche Veränderung führt dazu, dass die Methode nicht mehr funktioniert. Die Änderung der Sprint-Ziele während des Sprints wird gerne als besonders agil bezeichnet. Mit Scrum hat diese Art der Agilität aber nichts zu tun.

Gleiches gilt auch für CARDS+. Die Struktur des Wiki, die Bausteine und Prinzipien und Praktiken sind aufeinander abgestimmt. Nur im Wiki kann inkrementell dokumentiert werden. Die Bausteine sind so gestaltet, dass Wissen schrittweise erfasst wird, vom Groben ins Feine. Code und Test werden berücksichtigt und definieren die Grenzen der Produktdokumentation.

Ein Werkzeug

Jeder Mitarbeiter in der IT-Branche hat seine eigene Vorstellung von guter Dokumentation. Diese Vorstellung ist ganz maßgeblich von seinen persönlichen Schwerpunkten bestimmt. Jede Art der Dokumentation gibt es häufig in mehreren Ausprägungen. Auch bei der Wahl des «richtigen» Werkzeugs zum Schreiben der Dokumentation gibt es unterschiedliche Vorlieben.

Ein Product-Owner und Business-Analysten lesen Anforderungen und vermitteln Vision und Wissen zum Produkt. Sie nutzen in der Regel für ihre Dokumentation Office-Produkte oder ein Wiki (z.B. Confluence).

Entwickler benötigen Modelle, Spezifikationen, schreiben API-Dokumentation. Für API-Dokumentation gibt es beispielsweise «swagger« (REST-API), «javadoc» oder «doxygen». Entwickler wollen alles code-nah und nutzen für ihre Dokunentation daher gerne Markup-Dateien, aber auch «plain text» ist ok.

Tester kennen Testfälle, Testpläne, Teststufen. Testmethoden sind beispielsweise «test driven» oder «behavior driven». Tester denken häufig in Tabellen oder Listen und nutzen für ihre Dokumentation Office-Produkte (z.B. Excel) oder ein Wiki (z.B. Fitnesse).

Operatoren benötigen eine «knowledge base» mit Betriebsanweisungen und Online-Handbüchern zu den technischen Komponenten des IT-Systems.

«Viele Köche verderben den Brei» ist ein Sprichwort, das wahr wird, wenn jede Personengruppe die Dokumentation für ein Produkt so schreibt, wie sie es für richtig hält. Darum verfolgt CARDS+ den Ansatz, Wissen nur in einem Wiki zu erfassen, dass bestimmte Anforderungen erfüllt: Mit Seiten, Seitenhierarchie, Seitenvorlagen, Stichworte/Schlagworte, Kommentar- und Suchfunktion.

  • Product-Owner und Business-Analysten sind damit in der Regel sofort zufrieden. Mit den Bausteinen Topic, Epic und Case können sie eine Anforderung analysieren und die Ergebnisse schrittweise erfassen.
  • Für Entwickler und Tester bietet die Methode CARDS+ die Bausteine Service, Event und Entity, die Platzhalter für Code oder Testfälle in der Produktdokumentation sind.
  • Operatoren profitieren in den Betriebsanweisungen von den Hinweisen in den Bausteinen Service, Event und Entity.

Das Glossar sorgt für eine gemeinsame Sprache bei allen Personengruppen. Abbildungen und Diagrammen aus der Medienbibliothek vermitteln einen Überblick über Prozesse und Komponenten des IT-Systems. Mit dem Seitentitel von Bausteinen legen Product-Owner und das Team einen gemeinsamen Namen für interne Dienste (Baustein Service) oder Schnittstellen (Bausteine Event und Entity) fest. Nur Wissen, dass nicht durch lesbaren Code oder Testfälle besser beschrieben wird, erfassen Entwickler und Tester im Wiki.

Eine Struktur

Das «principle of least astonishment» ist eine goldene Regel in der Software-Ergonomie, Mensch-Computer-Interaktion und dem UX-Design. Sie lässt sich aber auch gut auf Dokumentation übertragen. Jeder Leser wünscht sich Informationen so aufbereitet, dass er sie gut aufnehmen kann. Er möchte eine Dokumentation mit einer nachvollziehbare Struktur. In der Struktur findet er genau die Informationen, die er dort erwartet, oder er kann gezielt danach suchen. Ein Wiki ohne Struktur erreicht auf Dauer keine Leser mehr. Nur mehr Autoren nutzen das Wiki.

Ein großer Vorteil einer festen Struktur mit Bausteinen ist die Möglichkeit, sie flexibel zu kombinieren, aus Bausteinen über gemeinsame Kriterien einen Katalog zu bilden.

In einem komplexen IT-System gibt es in der Regel viele verschiedene Dienste, die mit dem Baustein Service erfasst werden. Dienste basieren auf Technologien, z.B. für Persistenz, Messaging, Streaming und sind in einer bestimmten Programmiersprache implementiert. Nutzen wir Stichworte aus einem festgelegten Vokabular der Technologien, bekommen wir eine Zusammenstellung von Diensten je Technologie. So bekommt der Product-Owner einen Überblick, welche Fähigkeiten sein Team haben muss, um eine Komponente zu ändern.

Ein Messpunkt ist eine Anforderung für das Protokollieren eines besonderen Zustands oder eine Entscheidung im Verlauf der Datenverarbeitung in einer Komponente. Technische Messpunkte gibt es bei einer Exception oder einem Timeout. Starten und Stoppen einer Komponente ist ein Standard-Messpunkt, genau so der Lebenszyklus (also Anlegen, Ändern oder Löschen) eines wichtigen Objektes. Ein Messpunkt protokolliert auch eine Validierung oder die Lösung eines Konfliktes, die zum Verwerfen eines Datensatzes führte. Messpunkte werden mit einem Baustein Case dokumentiert, der inhaltlich auf ein Minimum reduziert wurde. Sie bilden einen Katalog von Messpunkten, die von der technischen und fachlichen Betriebsführung eines IT-Systems für Auswertungen und Monitoring nutzbar sind.

Die festen Abschnitte in jedem Baustein haben außerdem den Vorteil, dass sie formal geprüft werden können. Ein Prüfer ist selbst mit geringerem fachlichen Wissen als der Autor in der Lage, die Vollständigkeit eines Bausteins zu erkennen. Fehlt ein Abschnitt, dann ist der Baustein nicht fertig. Ist ein Abschnitt in einem Einzelfall nicht notwendig, dann muss der Autor zumindest einen Leervermerk mit dieser Begründung hinterlassen.

Ein Prozess

«Gut gemeint ist der kleine Bruder von schlecht gemacht» ist eine Binsenweisheit, die besonders im Zusammenhang mit Qualität sich immer wieder bestätigt. Es ist für einen Product-Owner oder Business-Analysten natürlich leichter, das gesammelte Wissen in einem Rutsch in einer Seite bzw. einem Dokument zu erfassen. Er wird das Wissen in Abschnitten strukturieren. Keine Frage. Er meint es gut und macht einen Vorschlag für eine Lösung, die auf seinen eigenen Erfahrungen und dem Projektumfeld basiert.

Trotzdem ist das schlecht für die Qualität. Langfristig betrachtet. Nach Abschluss der Analyse kommt die Umsetzung. Dann wird es neue Erkenntnisse oder Veränderungen geben, die das Wissen vertieft oder neues Wissen entstehen lässt. Durch Feedback soll dieses Wissen auch eingang in die Dokumentation finden. Es ist aber naturgemäß für Entwickler und Tester sehr schwierig, die passenden Stellen für das Feedback in einer umfassenden Dokumentation zu finden, deren Struktur er nicht gut kennt. Sie werden daher übergehen, das Feedback abstrakter zu formulieren und als E-Mail an Autor oder als Kommentar an die Seite schreiben. Der Autor hat dadurch Aufgabe, die Änderungen selbst einzupflegen. Durch diese zweimalige Abstraktion geht Zeit verloren. Bei der mehrfachen Überarbeitung geht Wissen verloren. Durch ein Missverständnis kann auch eine falsche Information entstehen.

Fazit

CARDS+ macht eine Reihe von Vorgaben. Es muss ein Wiki sein. Bausteine bestimmen eine feste Struktur. Autoren können nur das dokumentieren, wofür es einen Baustein gibt. Diese Vorgaben sind aber notwendig, damit eine Produktdokumentation als Ganzes auf Dauer pflegbar ist. Unter den Begriff Projektdokumentation fallen alle Arten von Dokumenten, für die es keinen passenden Bausteine gibt. Der Einsatz von CARDS+ schränkt nicht ein, sondern bedeutet nur, die Dokumentation in Produkt- und Projektdokumentation zu trennen.