Redenswerte

Redenswerte

Logo Redenswerte

Zur Bewältigung der anstehenden Aufgaben wurden unsere Teams verstärkt. Im Rahmen einer Reihe von Einführungsveranstaltungen durfte ich den neuen Entwicklern Silas Entner, Josef Eilers und Jan Eklund die Methode CARDS+ als Grundlage für unser Vorgehen zur fachlichen und technischen Dokumentation im Projekt vorstellen.


In einer sehr kurzen Einführung erzähle ich etwas über unser Confluence und unseren Ansatz für agiles Dokumentieren. Wir legen fest, dass wir uns maximal eine halbe Stunde Zeit nehmen, um über den Aufbau der Dokumentation und unser Vorgehen zu sprechen. Ich erkläre bereits am Anfang, dass es nicht um Dokumente des Projektalltages geht, d.h. keine Protokolle und andere Mitschriften, Analysen, Zwischenergebnisse, Organigramme, Aufgabenlisten, also ganz allgemein keine Dokumente, die irgendeine Art von Veränderung beschreiben oder für die Steuerung der Prozesse im Projekt notwendig sind. Ich betone, dass wir uns in dieser Veranstaltung nur mit dem fachlichen Teil der Produktdokumentation, der Systembeschreibung, beschäftigen werden.


Ich: Ich möchte gerne mit einer Frage fortfahren. Wer kennt den zweiten Punkt aus dem agilen Manifest?

SE: Soweit ich mich erinnern kann heißt es dort sinngemäß “Schätze funktionierende Software mehr als umfassende Dokumentation”.

Ich: Sehr gut. Was bedeutet das für uns?

JE: Das wir zuerst schauen, die Software zum Laufen zu bringen. Wir schließen die Programmierung ab, bevor wir uns um die Dokumentation kümmern.

Ich: Quasi als Nachdokumentation?

JE: Funktioniert genau wie alles andere in Scrum. In jedem Sprint ein bisschen. Ich würde natürlich den Aufwand so minimal wie möglich halten. Das Wissen für die Umsetzung neuer Anforderungen ist im Team vorhanden, der Product-Owner beantwortet uns jederzeit unsere Fragen. Und wir müssen eh immer den Code anschauen, wenn wir eine Änderung machen. Meine Erfahrung ist, dass die Doku eigentlich nie reicht.

Ich: Verstehe. Und für wen schreibst du am Ende diese Dokumentation?

SE: Wir schreiben die Doku, weil es im Projekt eine Vorgabe ist. So steht’s in der DoD.

Ich: Aha. Das stimmt. Aber ich habe den Eindruck, ihr haltet das Dokumentieren größtenteils für eine Zeitverschwendung?

SE: Naja, manchmal ist es schon lästig. Es frisst Zeit. Wir haben doch alle Informationen im Backlog, die wir brauchen.

Ich: Spannend. Du meinst also, dass das Backlog als Produktdokumentation reicht? Ich denke, es ist jetzt ein guter Zeitpunkt, um euch erst einmal zu erzählen, wie wir in diesem Projekt dokumentieren. Besonders wichtig ist mir, dass ihr die Ziele kennt, die wir mit unserem agilen Ansatz erreichen wollen.


In den nächsten zehn Minuten zähle ich alle Bausteine der Systembeschreibung auf. Anhand von konkreten Beispielen erkläre ich den Kollegen kurz die für unseren Entwicklungsprozess notwendigen Bausteine. Ich weise darauf hin, dass die Bausteine einen fixen Aufbau haben und im Wiki eine hierarchische Struktur bilden.

CARDS+ Realisierung

Ich betone außerdem die Wichtigkeit des Glossars und die Notwendigkeit, dass wir es alle gemeinsam von Beginn an konsequent pflegen.


Ich: Gibt es Fragen zur Systembeschreibung?

SE: Wer schreibt das alles?

Ich: Sehr gute Frage. Die Bausteine Topic, Epic, Case und Layout werden nicht zur gleichen Zeit geschrieben. Ein Topic entsteht, wenn der Product-Owner einen Aufgabenbereich bei der Realisierung unseres Produktes vom Auftraggeber übernimmt. Viele Topics wurden aus diesem Grund bereits beim Start des Projektes erstellt. Sie bilden den groben Rahmen für das Projekt.

SE: Dann schreibt der Product-Owner die Systembeschreibung?

Ich: Nicht ganz. Auch nicht alleine. Für den Inhalt eines Topic sind Auftraggeber und Product-Owner zuständig. Ein Topic hilft euch, das “große Ganze” zu verstehen. Ihr versteht, wer unser Produkt verwendet, wann und wieso er das tut. Die Bausteine Epic und Case sind das Ergebnis der Analyse der Anforderungen durch den Product-Owner und sein Team. Jedes Epic beschreibt eine Zusammenstellung von Funktionen, die in einem bestimmten Geschäftsprozess einen Wert schaffen, für die Nutzer unseres Produktes einen konkreten Bedarf befriedigen. Ein Epic nutzen wir zur Beschreibung der Motivation und für die Abgrenzung zu anderen Epics. Mit Cases und Layouts gehen wir ins Detail. Der Product-Owner beschreibt im Case die Ausgangslage und die konkreten Einzelfälle einer Funktion, die er bei der Analyse berücksichtigt hat. Die Lösung lässt er aber zu diesem Zeitpunkt noch offen. In einem Layout macht er oder ein UX-Designer einen Vorschlag für die Benutzeroberfläche.

SE: Du meinst, ein Case oder Layout bleibt unvollständig.

Ich: Richtig. Ein Case bleibt bezüglich der Lösung unvollständig, bis ihr als Team diese Lücke schließt. Das Refinement-Meeting bietet sich an, mit der Systembeschreibung und dem Wissen des Product-Owners, innerhalb der Rahmenbedingungen der Architekturdefinition eine valide Lösung zu finden. Beim Layout unterstützt euch zusätzlich ein UX-Designer.

SE: Mit dem Team meinst du uns, oder?

Ich: Ja, genau. Natürlich wird der Product-Owner die Seiten im Confluence anlegen. Aber ihr seid alle Leser und eine wichtige Zielgruppe. Wir brauchen das Feedback vom ganzen Team zu jeder Seite im Confluence. Egal, ob ihr einen Schreibfehler entdeckt, ein Verständnisproblem habt oder eine Lücke vermutet. Gebt Feedback als Kommentar. Die Dokumentation muss leben. Wir müssen als ganzes Team für die Qualität sorgen, wie wir es auch für Code und Test tun. Nutzt die Kommentarfunktion von Confluence als Erweiterung unsere Kommunikationsmöglichkeiten im Team. Ihr könnt jederzeit Feedback zu Topics, Epics, Cases und Layouts geben, die von den Stories im Sprint-Backlog betroffen sind. Vor, während und nach dem Sprint. Euer Feedback hilft dem Product-Owner beim Backlog-Management. Und Feedback als Kommentar ist für alle Leser sichtbar und nützlich.

SE: Wie soll das funktionieren? Ich kann doch nicht dauernd im Confluence lesen. Die Zeit habe ich nicht.

Ich: Du sollst auch nicht das ganze Confluence lesen. Der Product-Owner sorgt dafür, dass durch sein Backlog-Management die Topics und Epics für die Stories im Sprint-Backlog “fertig” sind. Und als Team habt ihr im Refinement- und Planning-Meeting gemeinsam mit dem Product-Owner dafür gesorgt, dass alle im kommenden Sprint relevanten Cases und Layouts vollständig beschrieben sind. Im Refinement-Meeting findet ihr eine geeignete Lösung und dokumentiert sie im Case. Im Planning-Meeting wird die Lösung durch das ganze Team bestätigt, in Aufgaben zerlegt und geschätzt. Alle wichtigen Erkenntnisse aus diesen Meetings wollen wir im Confluence sichern. Mit voller Transparenz für alle im Projekt. Und ich bin überzeugt, dass euch die Informationen später im Sprint helfen werden.

JE: Müssen wir jetzt alles im Confluence beschreiben? Ich dachte, unser Sprint-Backlog ist in JIRA?

Ich: Wir nutzen Confluence und JIRA. In Confluence befinden sich die Ergebnisse der Analysen, Gespräche und Meetings, die Vorfeld stattfinden. Erst wenn das Team eine Funktion verstanden hat und das Ergebnis als gemeinsames Verständnis von Product-Owner und Team in Confluence vorliegt, ist ein Case “reif” für eine Story in JIRA. In der Story beschreiben wir, was wir in unserem Produkt verändern müssen, um das im Case beschriebene Ziel zu erreichen. Die Akzeptanzkriterien der Story helfen uns zu prüfen, ob wir das Ziel erreicht haben. Das gleiche gilt übrigens auch für ein Layout.

SE: Warum sind die Akzeptanzkriterien nicht im Case?

Ich: Mit den Akzeptanzkriterien in JIRA prüfen wir, ob die Veränderung im Produkt abgeschlossen ist, wie es in Scrum üblich ist. In Confluence wollen bzw. dürfen wir keine Veränderung beschreiben. Wir trennen ganz klar zwischen Prozess und Produkt. Den Prozess unterstützen wir mit JIRA. Das Produkt beschreiben wir in Confluence.

JE: Heißt das, wir müssen alles doppelt dokumentieren? Einmal in Confluence, dann noch einmal in JIRA.

Ich: Nein, auf keinen Fall. In JIRA ergänzen wir nur, was nicht im Case steht. Also konkret stehen im JIRA die notwendigen Zusatzinformationen zur Änderung der Software. Wir beschreiben, was wir ändern müssen, um im Produkt die neue Funktion zu erschaffen, wie sie im Case beschrieben ist. Nur in JIRA zerlegen wir die Aufgabe in Tasks, um sie im Team zu verteilen. Es ist häufig notwendig, einen Case sogar mit mehr als eine Story umzusetzen, z.B. eine Story für die Funktion und weitere für die Umsetzung von nicht-funktionalen Aspekten. Eine Story bekommt durch die Akzeptanzkriterien einen prüfbaren Umfang. Im Case hingegen steht alles Wissenswerte zum Produkt, eine Beschreibung des Problems oder der Aufgabe aus Sicht der Nutzer. Und in der Lösung dokumentieren wir die Sicht der Entwickler. Im Case ist das Produktwissen, in der Story der Arbeitsauftrag.

SE: Okay, wir teilen die Doku auf, nutzen Confluence und JIRA. Was bringt uns das wirklich?

Ich: Der wesentliche Vorteil ist, dass wir am Ende des Sprints alle Stories archivieren oder sogar löschen können. Niemand wird sie mehr brauchen. Es steckt keine Information in den Stories, die wir nach dem Sprint noch brauchen. Alles Wissenswerte zum Produkt steckt im Confluence, im Code oder in den Akzeptanztests. Und das wichtigste dabei ist, dass niemand zusätzlich dokumentieren muss, weil wir Dokumentation, Code und Test gleichzeitig erstellen oder ändern.

SE: Das klingt ja fast so, als ob Dokumentieren wie Programmieren funktioniert. Statt IntelliJ ist es Confluence. Die einen schreiben Java, die anderen in natürlicher Sprache.

Ich: Ja genau, so sehe ich das tatsächlich. Ich denke, Prinzipien wie KISS oder DRY sind auch für beim Dokumentieren hilfreich. Um gute Qualität in einer Dokumentation zu erreichen, muss sie prüfbar sein. Eine klare Struktur macht sowohl Code als auch Dokumentation nachvollziehbar. Lesbaren Code und für jeden verständliche Dokumentation erreichen wir nur durch eine gemeinsame Sprache im Projekt. Darum ist das Glossar so wichtig.


An diesem Punkt schaue ich auf meine Uhr und erkenne, dass wir das Ende unserer Timebox erreicht haben. Ich gebe noch den Hinweis, dass es neben den Bausteinen für die Systembeschreibung auch Bausteine für Architekturdefinition gibt, dir wir in einem weiteren Meeting besprechen werden. In einem sehr knappen Schlusswort erzähle ich etwas über Architekturentscheidungen und geben einen Überblick über die Bausteine für die Beschreibung der Systemstruktur. Das Meeting ist damit zu Ende.