Skip navigation

Agil dokumentierenAgil dokumentieren

199 members | 177 posts | Public Group

Mit cards+ wird inkrementelles Doku­men­tieren in einem agilen Software-Entwicklungsprozess zur leist­baren Auf­gabe. Die Doku­men­te werden prüfbar, die Qualität messbar.

Der Baustein Epic gehört zur Systembeschreibung. Er gibt einer pro­dukt­spezi­fischen Funk­tio­nali­tät einen ein­deu­tigen Namen und ent­hält eine fach­liche Beschrei­bung. Er bün­delt eine mit den Anfor­derun­gen wach­sende Menge von fach­lich verwand­ten Fähig­kei­ten der Soft­ware, die mit dem Bau­stein Case doku­men­tiert wer­den.

https://cardsplus.info/de/struktur/Epic/

Der Bau­stein Epic hilft dem Pro­dukt­verant­wort­lichen bei der Sicherung der Ergeb­nisse der Anfor­derungs­analyse. Eine von Auf­trag­geber und inter­essierten Par­teien akzep­tierte Beschrei­bung der Funktio­nali­tät des Pro­duktes stellt den zwei­ten Schritt der Vali­die­rung einer Anfor­derung dar. Der Produkt­­verant­wort­liche hat mit dem Baustein Epic die Mög­lich­keit, eine pro­dukt­­spezifische Funktio­nali­tät vor­läufig zu beschrei­ben und von anderen Funktionalitäten abzugrenzen. Das ist immer dann sehr hilfreich, wenn durch Fluktuation beim Auftraggeber Wissen über Entscheidungen verloren gehen.

***

Wann wird ein Epic erfasst?

Der Auf­trag­geber legt fest, welche Anfor­derungen an das IT-System ge­stellt werden. Der Pro­dukt­verantwort­liche nutzt den Bau­stein Epic, um diese wich­tige Ent­schei­dung des Auf­trag­gebers für oder gegen die Reali­sierung einer angefor­derten Funktio­nali­tät nach­haltig zu doku­mentieren.

Wer erstellt ein Epic?

Der Produktverantwortliche! Er vertritt das Produkt sowohl in fachlicher als auch finanzieller Sicht. Eine Funktionalität muss sinnvoll sein, einen Wert haben, genutzt werden.

Darf ein Epic geändert werden?

Ja, natürlich. Mit dem Fortschreiten der Entwicklung schärft sich immer auch das Verständnis für die Funktionalität des Produktes. Diese Erkenntnisse sind wertvoll und sollten in der Produktdokumentation gesichert werden.

Darf ein Epic gelöscht?

Ja, natürlich. Ein Epic wird gelöscht (oder besser archiviert), wenn die Funktionalität aus dem Produkt entfernt wird.

***

Weitere Fragen beantworte ich sehr gerne. Nutzen Sie einfach die Kommentarfunktion.

Ich habe kürzlich an einer persönlichen Weiterbildung teilgenommen, bei der ich von einem Profi (u.a. Coach bei der PULS4-Show 2 Minuten 2 Millionen) in die Geheimnisse des "pitchens" eingeweiht wurden. Ich habe gelernt, dass die ersten Sätze in einem Pitch entscheidend sind. Sie müssen Interesse wecken, die Zuhörer neugierig machen. Als nächstes sollte das Problem dargestellt werden und "verlängert" werden. Verlängern heißt, aus dem ursprünglichen Problem (engl. root cause) Konsequenzen abzuleiten, durchaus mehrstufig. Erst dann präsentiert man seine Lösung.

Gelerntes soll man ja sofort anwenden, um es zu vertiefen. Darum versuche ich spontan einen Pitch für cards+.

EINSTIEG

Eine Software besteht aus Quelltexten, Testplänen und weiteren dokumentierten Informationen. Quelltext klar, das ist das Produkt. Testpläne in einer Testpyramide sichern die Qualität des Produktes. Weitere dokumentierte Informationen sind Verträge, Aufträge, Anforderungen, User-Storys, Studien, Grob- und Fachkonzepte, Analysen, Handbücher, Online-Hilfen u.v.m. In Projekten mangelt es in der Regel nicht an Dokumentation. Wollen wir Software erfolgreich über einen längeren Zeitraum betreiben, dann müssen unsere Entwickler kontinuierlich Fehler beheben, Patches und Updates einspielen und neue Anforderungen umsetzen. Dazu müssen die Entwickler nicht nur den Quelltext verstehen, sondern das Produkt als Ganzes.

PROBLEM

Durch Fluktuation bei den interessierten Parteien oder in der Projektorganisation geht uns Wissen verloren. Nun, sie werden sagen, dass alles Wissen im Quelltext steckt. Ja, Wissen steckt im Quelltext. Der Quelltext beantwortet die Frage, wie etwas gelöst wurde. Testpläne beantworten die Frage, was das Produkt nachweislich leistet. Aber die Frage, warum das Produkt gebraucht wird, wer es einsetzt und welchen Zweck er dabei verfolgt, das kann nur durch die weiteren dokumentierten Informationen beantwortet werden. Und das ist der Kern des Problems: Diese Informationen sind in der Regel veraltet, widersprüchlich, falsch.

Ein Fachkonzept kann formal völlig in Ordnung sein, und war wahrscheinlich zum Zeitpunkt der Freigabe auch korrekt. Aber durch jede Fehlerbehebung, Umsetzung einer Anforderungen oder Änderung im Design der Software entsteht eine Abweichung vom ursprünglichen Konzept. Software wird kontinuierlich verändert. Konzept und Software passen sehr bald nicht mehr zusammen. Fachkonzepte werden mit der Zeit unbrauchbar, wenn sie nicht aktualisiert werden. Und das passiert sehr selten. Die Gründe sind vielfältig. Aber das ist eine ganz andere Geschichte.

Ein Handbuch kann einem Entwickler helfen, das Produkt zu verstehen. Aber ein Handbuch wird aus der Perspektive der Nutzer geschrieben. Ein Handbuch sieht die Software immer als Blackbox, von außen. Ein Handbuch kann daher einem Entwickler nichts über die Gründe für den Entwurf der inneren Struktur der Software sagen.

Die Liste der dokumentierten Informationen, die einem Entwickler *nicht* helfen, ist sehr, sehr lang. Frustrierend lang. Falsche Dokumentation birgt zusätzlich die Gefahr, dass unsere Entwickler in die Irre geführt werden. Und das kostet Geld.

LÖSUNG

Die Lösung ist eigentlich ganz einfach. Wir brauchen eine Produktdokumentation, auf die wir uns verlassen können. Neben dem Quelltext und den Testplänen des Produktes muss von Anfang an auch die Dokumentation für das Produkt inkrementell erarbeitet und mit dem Fortschritt der Entwicklung kontinuierlich verbessert werden. Dokumente müssen wie Quelltext betrachtet und versioniert werden. Dokumente müssen strukturiert sein. Sie müssen prüfbar sein. Ihre Qualität muss messbar sein. Im Grunde gelten sehr viele Praktiken der Entwickler auch für Autoren einer Dokumentation: KISS, DRY, INVEST, die Pfadfinderregel. Das gemeine ist, dass Entwickler schon sehr lange geeignete Strategien haben, um die Komplexität von Software in den Griff zu kriegen. Sie wählen Strukturen, die besser testbar sind als andere. Sie modularisieren. Sie delegieren. Sie kapseln.

Mit cards+ gibt es ein Konzept, das solche Strategien auch für eine Produktdokumentation bietet. cards+ macht es möglich, die Ergebnisse aus der Analyse (z.B. mit Domain-Driven Design) direkt in ein Wiki zu übernehmen. cards+ ist ein in sich geschlossenes Ökosystem von Bausteinen. Jeder Baustein hat einen klaren Zweck, eine prüfbare Struktur und einen für den Inhalt verantwortlichen Autor. Die Bausteine sind aufeinander abgestimmt mit dem Ziel, jede Information nur einmal zu erfassen. Im Wiki ist jeder Baustein eine Seite. Bausteine bilden Hierarchien (z.B. Topic, Epic und Case) oder werden miteinander verknüpft (z.B. Begriffe aus dem Glossar, die Lösung in einem Case).

Bei cards+ gibt es ein einfaches Kriterium, das beim Aussortieren von Information hilft. Eine Information, für die es einen passenden Baustein in cards+ gibt, wird dauerhaft erfasst und inkrementell gepflegt. Alle andere Informationen, die zu einem bestimmten Zeitpunkt zwar wichtig und notwendig sind, später aber nicht mehr gebraucht werden, gehören zur Projektdokumentation. Dazu zählen beispielsweise User-Stories in einem Backlog, Studien oder Analysen.

Mit cards+ werden Entwickler zu Autoren, ohne sich extra anstrengen zu müssen. Sie nutzen Formate wie Asciidoc für Spezifikationen, die sich wie Code anfühlen. Sie nutzen Formate wie JSON, XML oder YAML für Konfigurationen, die durch Kommentare lesbar sind. Sie generieren Dokumentation direkt aus dem kommentierten Code. cards+ als Werkzeug macht dokumentierte Informationen im Quelltext und in Testplänen für die Dokumentation im Wiki nutzbar.

Wird das Konzept cards+ von Anfang an in der Projektorganisation gelebt, dann ist eine hochwertige Produktdokumentation keine Illusion mehr. Der Aufwand für die Herstellung der Dokumentation mit den Prinzipien und Praktiken von cards+ unterscheidet sich nicht von dem Aufwand, Dokumente "irgendwie" zu schreiben. Aber die Chancen, die sich durch eine strukturierte Produktdokumentation in einem Wiki ergeben, sind nur durch die Kreativität der Personen beschränkt, die sie lesen und pflegen.

https://cardsplus.info/

Der Baustein Topic gehört zur Systembeschreibung. Er beschreibt einen klar abge­grenz­ten Auf­gaben­bereich (engl. scope), in dem das IT-System Ver­wen­dung fin­det. Er bün­delt eine mit den Anfor­derun­gen wach­sende Menge von zusammenhängenden Funktio­nali­täten, die mit dem Bau­stein Epic doku­mentiert wer­den.

https://cardsplus.info/de/struktur/Topic/

Der Bau­stein Topic hilft dem Pro­dukt­verantwort­lichen bei der Sicherung der Ergeb­nisse der Anfor­derungs­ana­lyse. Jede Anfor­derung an das Pro­dukt muss ein Pro­dukt­verant­wort­licher zusammen mit dem Auf­trag­geber, unter­stützt durch andere inter­essierte Par­teien (z.B. Nutzer), ein­deutig einem existierenden Auf­gaben­bereich des Pro­duktes zuor­dnen. Das sollte in den meisten Fällen problem­los gelingen und stellt den ersten Schritt der Vali­dierung einer Anfor­derung dar. Eine erfolg­reiche Zuord­nung bedeutet, dass die Anfor­derung eine sinn­volle Erwei­terung des Pro­duktes dar­stellt und daher in der Regel reali­siert werden kann, unge­achtet anderer Rand­bedingungen wie Zeit und Geld.

Mit dem Einsatz von Domain-Driven Design für strate­gisches und takt­isches Design wird die Modellie­rung der Fach­lich­keit in den Vorder­grund gestellt. Der Baustein Topic kann genutzt werden, um die Grenzen (engl. boundaries) im System zu dokumentieren..

https://cardsplus.info/de/cards-und-ddd/

***

Wann wird ein Topic erfasst?

Der Auf­trag­geber legt fest, in welchen Auf­gaben­bereichen das IT-System einge­setzt wird und nimmt Bezug auf die Prozesse der Nutzer, in denen das Pro­dukt eine Rolle spielt. Der Pro­dukt­­verant­wort­liche hat mit dem Bau­stein Topic die Möglich­keit, die “Lei­tplanken” für das IT-System bereits bei der Projektinitialisierung zu doku­mentieren. Mit den Worten des Auftraggebers.

Wer erstellt ein Topic?

Der Produktverantwortliche! Er vertritt das Produkt sowohl in fachlicher als auch finanzieller Sicht. Und der Umfang eines Produktes hat direkte Auswirkung auf die Kosten.

Darf ein Topic geändert werden?

Ja, natürlich. Mit dem Fortschreiten der Entwicklung schärft sich immer auch der Umfang des Produktes. Der Überblick im Baustein Topic sollte daher mindestens dann angepasst werden, wenn der Umfang sich in Abstimmung mit dem Auftraggeber ändert. Häufig wird erst beim Entwickeln klar, was nicht zum Umfang gehört. Auch diese Abgrenzung sollte in einem Topic Niederschlag finden.

Darf ein Topic gelöscht?

Ja, natürlich. Ein Topic wird gelöscht (oder besser archiviert), wenn der Umfang des Produktes entsprechend reduziert wird.

***

Weitere Fragen beantworte ich sehr gerne. Nutzen Sie einfach die Kommentarfunktion.

Der Baustein Term gehört zur Systembeschreibung. Er reali­siert das Kon­zept für ein Glos­sar. Mit dem Bau­stein wird ein wich­tiger Begriff der Anwen­dungs­domäne, in der die Soft­­ware zum Ein­­satz kommt, zen­­tral und ver­­link­­bar im Wiki er­fasst. Der Aufbau ist sehr einfach. Er besteht nur aus einer Begriffsdefinition.

https://cardsplus.info/de/struktur/Term/

Der Baustein Term realisiert das Prinzip DRY. Es gibt nur eine Definition für einen Begriff. Andere Dokumente nutzen diese Begriffsdefinition durch Verlinken oder Einbetten. Dadurch profitieren diese Dokumente von der kontinuierlichen Verbesserung im Glossar. Die Autoren dieser Dokumente werden indirekt gezwungen, die Begriffe korrekt zu verwenden. Widersprüchliche Verwendung von Begriffen wird von den Lesern der Dokumente leichter identifiziert.

https://cardsplus.info/de/methode/DRY/

Mit dem Einsatz von Domain-Driven Design für strate­gisches und takt­isches Design wird die Modellie­rung der Fach­lich­keit in den Vorder­grund gestellt. Es entsteht eine domänen­spezi­fischen Sprache. Der Baustein Term dokumentiert diese gemeinsame Sprache.

https://cardsplus.info/de/cards-und-ddd/

***

Was ist ein wichtiger Begriff?

Ein Begriff ist wichtig, wenn er häufig genutzt wird. Ein wichtiger Begriff bringt etwas "auf den Punkt" und wird von jeder interessierten Partei verstanden.

Wann wird ein wichtiger Begriff erfasst?

Ein Begriff wird erfasst, sobald er in der Kommunikation der interessierten Parteien genutzt wird. Bereits bei der Projektinitialisierung werden erste wichtige Begriffe erfasst.

Wer erstellt Begriffe im Glossar?

Der Produktverantwortliche und weitere Domänenexperten! Sie kennen das Produkt und gestalten damit die gemeinsame Sprache im Projekt.

Darf ein Begriff geändert werden?

Ja, natürlich. Aber konsequent, also auch in der Software.

Darf ein Begriff übersetzt werden?

Das hängt vom Projektumfeld ab. Der Begriff wird in der Sprache der Anwendungsdomäne definiert. Nur so kann er exakt definiert werden. Unterscheidet sich die Sprache der Anwendungsdomäne von der Sprache in der Projektorganisation, dann kann der Baustein Term auch eine Übersetzung enthalten.

***

Weitere Fragen beantworte ich sehr gerne. Nutzen Sie einfach die Kommentarfunktion.

Domain-Driven Design kennen und nutzen Software-Entwickler seit [Evans2004] schon lange. [InfoQ2006], [Vernon2013] und [InnoQ2020] widmen sich diesem Thema ausführlich. Ich vertrete die Meinung, dass jede nicht triviale Software dokumentiert werden muss. Sich auf implizites Wissen in den Köpfen der Entwickler zu verlassen, halte ich persönlich für ein zu großes Risiko. Domain-Driven Design gibt hier keine eindeutige Antwort. Natürlich ist das Domänenmodell Dokumentation. Natürlich ist die gemeinsame Sprache wertvolles Wissen. Lesbarer, sauberer Code ist in der Regel ein erklärtes Ziel der Entwickler.

Ich beschäftige mich mit diesem Thema seit 2014 sehr intensiv. Mein Ziel ist es, den Entwicklungsprozess so zu gestalten, dass für Code, Tests *und* Dokumentation die gleichen Maßstäbe für Qualität gelten. Was liegt also näher, als "building blocks" für dokumentierte Informationen zu schaffen und sie im taktischen Design der Software fest zu verankern. Diese Idee verfolge ich mit den Bausteinen von cards+.

In einer Reihe von Beiträgen möchte ich darum diese Bausteine präsentieren. [Cards2020] ist der Einstieg für Ungeduldige. Fragen beantworte ich sehr gerne.

---

[Cards2020] https://cardsplus.info/de/struktur/#10

[Evans2004] Evans Eric; Domain-Driven Design, 2004.

[InfoQ2006] https://www.infoq.com/minibooks/domain-driven-design-quickly/

[Vernon2013] Vernon Vaughn, Implementing Domain-Driven-Design, 2013.

[InnoQ2020] https://www.innoq.com/de/articles/2020/02/warum-domain-driven-design/

Hallo Robert, mit interesse habe ich insbesondere die Ausformulierung und Klärung der Funktion des Bausteins Epic gelesen. Damit bietet er die Funktion, an deren Fehlen ich mich mit Dir so vortrefflich reiben konnte. Durch den Epic als zentrale Verbindung zur Anforderungsanalyse und fachlichen Detailbeschreibung findet nun auch der Fachdienst seinen Platz in cards+, das hatte in der bisherigen Struktur, die ich mir 2018 zuletzt angeschaut hatte gefehlt. Mit dem in meinem Team geschaffenen Ansatz, Anforderungen in Form eines "UseCase" getauften Dokuments zu beschreiben, welches dann in einzelne, detailliertes fachliches Verhalten beschreibende "Aspekte" herunter gebrochen wird, haben wir ein gutes Mapping auf die Bausteine "Epic" und "Case" im cards+ Der Inhaltliche Teil des Epic und Case kann praktisch aus dem Overview des UseCase bzw. Aspekt über- bzw. entnommen werden, so dass sich keine doppelte Buchführung in der Dokumentation einstellen sollte. Sehr gelungen, vielen Dank für den Ansatz!
Die Methode CARDS+

Mit dem Ein­satz von cards+ ist eine agile Pro­jekt­organi­sation in der Lage, ziel­gerich­tet und itera­tiv eine Pro­dukt­doku­men­tation zu ent­wickeln. Ziel­gerich­tet bedeu­tet, dass die erstell­ten Doku­mente einen Wert für die Organi­sation haben. Mit dem Fort­schritt in der Ent­wick­lung der Soft­ware wächst auch die Pro­dukt­doku­men­tation, als inte­gra­ler Bestand­teil des Pro­dukt­inkre­men­tes. Doku­men­tieren wird zur leist­baren Auf­gabe des gesam­ten Teams. Die Doku­men­tation wird prüf­bar, die Quali­tät mess­bar.

Doku­men­tieren bleibt trotz­dem ein Reiz­wort. Es gibt die einen, die auf Doku­men­tation ver­zich­ten wollen. »Code und Test­pläne reichen!«, sagen sie. Andere wollen wieder­rum alles ganz genau auf­schrei­ben. »Das Wissen darf nicht ver­loren gehen!«, for­dern sie. In diesem Span­nungs­­­­feld bewegt sich cards+.

Durch Fluk­tuation oder durch Ver­änderun­gen im Unter­nehmen ent­steht ein regel­mäßiger Wech­sel in der Pro­jekt­organi­sation. Damit ver­bunden ist immer die Gefahr des Ver­lus­tes von Wissen. Der Ver­lust von Wissen ist gefähr­lich. Die Pro­dukt­vision geht ver­loren. Quali­tät und Pro­duk­tivi­tät sinkt. Anpassun­gen und Erweiterun­gen der Soft­ware werden schwieri­ger. Inter­essier­ten Par­teien ist nicht klar, was die Soft­ware bereits leis­tet. Ent­wick­ler sind weni­ger moti­viert, da sie in altem Code wüh­len müssen, um zu ver­ste­hen, wie die Soft­ware »tickt«. Ihre Inno­vations­kraft sinkt.