Anforderungen langfristig dokumentieren, im agilen Umfeld

 

In unserem CARS-Training diskutieren wir viele Themen, unter anderem: wie dokumentiert man Anforderungen langfristig, im agilen Umfeld?

Diese Frage ist für uns deshalb so wichtig, weil der Wert der Dokumentation mit der Zeit zunimmt.

Beginnen möchte ich mit zwei Optionen zur langfristigen Dokumentation, die im agilen Umfeld nicht sinnvoll sind.
Dann möchte ich sinnvolle Optionen aufzeigen. Jeweils mit Vor- und Nachteilen.

Keine sinnvolle Option: Detaillierte Vorabspezifikation

Es ist nicht sinnvoll, alle Anforderungen vorab detailliert zu spezifizieren.
Im komplexen Umfeld gibt es häufig Änderungen. Anforderungen werden umpriorisiert. Das ist gerade ein Vorteil der agilen Entwicklung.
Manche Anforderungen werden angedacht, aber nie umgesetzt. Oder nicht so wie gedacht, weil man während der Entwicklung neue Erkenntnisse gewinnt.
Diskussion und Dokumentation einer Anforderung kostet Zeit. Wird die Anforderung nicht so umgesetzt wie dokumentiert, war es Zeitverschwendung. Zeit, die in der Entwicklung dringend gebraucht wird.

Auch keine sinnvolle Option: Das Backlog

Man beginnt, agil zu arbeiten. Vielleicht denkt man: jetzt gibt es keine Detailspezifikation mehr. Aber ein Backlog. Dann dokumentieren wir die Anforderungen langfristig damit.
Ein Backlog dient aber der Zukunft, nicht der Vergangenheit. Es ist eher als To-Do-Liste zu betrachten. Was setzen wir als nächstes um?
Das Backlog ist keine sinnvolle Option für die langfristige Dokumentation. Es dokumentiert nicht, was bereits umgesetzt wurde.

Option 1: Archivieren der User Stories nach der Umsetzung

Im CARS-Training erzählte ein Teilnehmer, seine Firma verwalte User Stories in JIRA. Die Entwickler archivieren sie nach der Umsetzung. Man kann dieses Archiv natürlich langfristig durchsuchen. Der Teilnehmer berichtete, dass es gut funktioniere.

Ein agiler Pragmatiker kann da schwer widersprechen. Was  funktioniert, funktioniert. Zumindest in einem bestimmten Kontext.

Ich sehe 2 Risiken dieses Ansatzes:

• Zu viele Details: Um die User Stories langfristig verwenden zu können, dokumentiert man sicher viele Details. Was, wenn die Details nicht wie geplant umgesetzt werden können? Werden die User Stories nachträglich noch angepasst? Eventuell dokumentieren die Stories die Implementierung nicht mehr korrekt.
• Delta- statt Systemdokumentation: User Stories beschreiben, was zu tun ist. Das “Delta” vom aktuellen Stand zum Sollstand. Um nachträglich den Ist-Stand herauszufinden, muss man eventuell mehrere User Stories analysieren. Den User Stories fehlt es an Kontextinformation. Sie sind keine Systemdokumentation, sondern nur ein kleines Fragment.

Option 2: Inkrementelle Erweiterung der Systemdokumentation

Man kann die Anforderungsdokumentation kontinuerlich pflegen.

Konkret: während eines Scrum-Sprints dokumentiert man den aktuellen Ist-Stand. Die Anforderungen, die gerade eben umgesetzt wurden. Die Dokumentation wächst über die Zeit. Sie wird inkrementell ergänzt.

Wenn man diesen Ansatz konsequent verfolgt, hat er einen großen Vorteil. Man erhält eine stets aktuelle Systemdokumentation. Sie dokumentiert, welche Anforderungen wirklich umgesetzt wurden.

Eine Herausforderung bei dieser Option ist Disziplin.

Nur, wenn man wirklich konsequent dokumentiert, bleibt die Dokumentation aktuell. Und das kostet Zeit, die vielleicht an anderer Stelle fehlt.

Außerdem ist nicht jeder Entwickler der geborene Dokumentierer. Wenn die Entwickler jedoch nicht selbst dokumentieren, sondern diese Aufgabe andere Mitarbeiter übernehmen, dann besteht die Gefahr des Informationsverlustes.

Eine Möglichkeit, diese Disziplin teamintern zu fördern, ist das Festhalten in der Definition of Done. In etwa so: “Systemdokumentation wurde aktualisiert”. Dies kann dann im Sprint Review kontrolliert werden.

Option 3: Anforderungen im Code

Eine völlig unterschätzte Art der langfristigen Dokumentation ist der Code der Software. Wenn man Code geeignet strukturiert und Namenskonventionen benutzt, kann man Dokumentation aus dem Code generieren.

Um das zu vereinfachen, habe ich eine Bibliothek entwickelt. Mit ihr kann man im Code lauffähige Use-Case-Modelle spezifizieren.

Hier ist ein (gekürztes) Code-Beispiel für einen Use Case zum Online-Einkaufen:

UseCaseModel useCaseModel = modelBuilder.useCase("Buy product")
    .basicFlow()
        .step("S1").system(startWithEmptyShoppingCart)
        .step("S2").system(displayProducts)
        .step("S3").user(addProductToCart).system(addProductToPurchaseOrder).reactWhile(lessThan10Products)
        .step("S4").user(checkOutPurchase)
        .step("S5").system(displayShippingInformationForm)
        .step("S6").user(enterShippingInformation).system(saveShippingInformation)
        .step("S7").system(displayPaymentDetailsForm)
        .step("S8").user(enterPaymentDetails).system(savePaymentDetails)
        .step("S9").system(displayPurchaseOrderSummary)
        .step("S10").user(confirmPurchase).system(initiateShipping)
        .step("S11").continueAt("S1")	

Daraus kann man etwa folgende Dokumentation generieren:

Use Case: Buy Product

Basic Flow

 

Der Clou: Der Code steuert die Anwendung und ist die Quelle für die Dokumentation.

Der Vorteil liegt auf der Hand: Mit geringem Aufwand kann man aus dem Code Dokumentation generieren. Sie spiegelt das tatsächliche Verhalten der Software wider.

Natürlich erfordert auch dieser Ansatz Disziplin. Besonders die Entwickler sind gefragt. Bevor man den Ansatz in der Breite einsetzt, sollte man ihn ausprobieren. Passt er für die Art der entwickelten Software?

Vollständigkeit erreicht man damit nicht. Man kann Qualitätsanforderungen wie Robustheit nicht einfach aus dem Code generieren.

Das Projekt requirementsascode ist auf Github frei verfügbar. Einfach mal ausprobieren.
Ich freue mich über Feedback.

Welche Optionen kennen Sie?

Kennen  Sie weitere Optionen für die langfristige Dokumentation? Dann möchte ich Sie einladen.

Hinterlassen Sie einen Kommentar zu diesem Artikel.

Oder kommen Sie in unser CARS-Training, und diskutieren ihren Ansatz mit mir und den anderen Teilnehmern.