Agil dokumentieren

Agil dokumentierenAgil dokumentieren

207 members | 190 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.

Die Methode CARDS+

... Log in to read more

In diesem Podcast diskutieren Sebastian und Ina mehr als eine Stunde lange über agile Dokumentation. Ausgehend vom Leitsatz aus dem Manifest agiler Software-Entwicklung, ein lauffähiges Produkt höher zu priorisieren als umfassende Dokumentation, sprechen sie u.a. über die Arten der Dokumentation, Zeitpunkt der Erstellung, Chancen durch Clean-Code, Behaviour-Driven-Development oder Automatisierung.

http://meinscrumistkaputt.de/folge-109-agile-dokumentation/

Ich persönliche finde es interessant, dass das erst in der Folge 109! zum ersten Mal das Thema Dokumentation behandelt wird. Ist das Thema wirklich so unwichtig?

Das Ziel agiler Entwicklung ist es, den Entwicklungsprozess flexibler und schlanker zu gestalten, als das bei den klassischen Vorgehensmodellen der Fall ist. Man möchte sich mehr auf die zu erreichenden Ziele konzentrieren und stärker auf technische und soziale Probleme bei der Entwicklung eingehen. Die Werte agiler Entwicklung bilden das Fundament agiler Methoden und Vorgehensmodelle. Der Ansatz von Scrum ist empirisch, inkrementell und iterativ. Er beruht auf der Erfahrung, dass viele Projekte zu komplex sind, um in einen vollumfänglichen Plan gefasst werden zu können. Aber Scrum sagt nichts darüber aus, wie ein Produkt dokumentiert wird.

Agil dokumentieren bedeutet für mich vor allem, nur das zu dokumentieren, was nicht bereits durch die Entwickler im Code oder durch die Tester als Testfall ausreichend genau beschrieben wurde. Ein Ziel muss sein, diesen Quell an Informationen für alle Projektmitglieder zu erschließen.

Die Frage, wie agiles dokumentieren aussieht, habe ich vor einiger Zeit in einem Scrum-Forum gestellt. Ich bekam ein paar sehr interessante Antworten.

> Funktioniert genau wie alles andere in Scrum. Jeden Sprint ein bisschen und die Dokumentation ist zusätzlich Teil der Definition of Done (DoD).

Eine DoD bei Code basiert in vielen mir bekannten Projekten auf Metriken. Schwachstellen (engl. code smells) und Gefährdungen (engl. vulnerabilities) werden bewertet und gezählt. Duplizierter Code wird identifiziert und gezählt. Die Testabdeckung von Code wird gemessen. Das sind nur Beispiele. Wie funktioniert eine messbare DoD bei Dokumentation?

> Die Dokumentation kann vom PO als Story priorisiert werden - und somit auch "potentiell lieferfähiges Produkt" sein.

Interessanter Punkt. Für das Schreiben von Tests wird keine Story verlangt. Setzt ein Projekt auf DevOps, gehört Deployment zur DoD. Es gilt: you build it, you run it. Eine Story ist erst fertig, wenn das Produkt installiert wurde. Ich frage mich darum, warum es für eine Dokumentation ein Story geben muss?

> Unsere Dokumentation ist das Backlog.

Ein gut priorisiertes agiles Backlog ist extrem wichtig. Keine Frage. Es ist aber mehr als To-Do-Liste zu verstehen. Nach Abschluss aller Stories in einem Backlog ist das Produkt fertig.

Stories werden häufig nach dem CCC-Modell geschrieben. Die Anforderung für eine Story muss auf einer Karte (engl. card) Platz finden. Die Story ist ein token, das die eigentliche Anforderung repräsentiert. Sie soll vor allem die Kommunikation (engl. communication) fördern und Akzeptanzkriterien (engl. confirmation) festlegen. Eine Story in einem Backlog enthält darum niemals jene Informationen, die durch Kommunikation erarbeitet werden.

> Unsere Dokumentation ist der Code.

Das ist nicht falsch. Code beantwortet auf jeden Fall die Frage, wie das Produkt funktioniert. Aber Code alleine beantwortet nicht die Frage, warum der Code das tut.

Mit großem Intetesse habe ich den Beitrag `Gute Programmierer - schlechte Software` im Online-Magazin Informatik Aktuell gelesen.

https://www.informatik-aktuell.de/entwicklung/methoden/warum-software-selten-dem-stand-der-technik-entspricht.html

Ich schätze mich selbst als guten Progrrammierer ein. Gute Software zu produzieren war immer mein Ziel. Der Begriff Stand der Technik schien mir bis jetzt klar.

> Der Stand der Technik ist kein technischer Begriff, sondern ein juristischer.

Es handelt sich um eine sogenannte Technikklausel – ein in vielen Gesetzestexten verwendeter, aber nicht im Detail im Gesetz definierter Begriff. Entwickelt man kommerzielle Software, so muss diese auf bewährten, zielgerichteten, fortschrittlichen Techniken und Technologien beruhen. Wer Software am Stand der Technik entwickelt, tut gut daran, eine Liste aller verwendeter Techniken und Technologien bereitzuhalten. Mit dieser auch _Bill of materials_ genannten Liste kann man jederzeit nachweisen, dass die zuvor genannten Bedingungen erfüllt und die Software am Stand der Technik ist. Die Liste sollte dann bei der Aufnahme jeder weiteren Technik oder Technologie aktualisiert werden.

Dass Software nicht dem Stand der Technik entspricht, ist vielen Beteiligten nicht klar. Und wenn, dann sehen sie es nicht als Manko ihrer eigenen Leistung. Software, die nicht dem Stand der Technik entspricht, kann jedoch juristische Folgen nach sich ziehen.

> Moderne Architekturen, Programmiersprachen, Technologien und Werkzeuge sind nicht unbedingt Stand der Technik.

Erfahrene Entwickler sind häufig davon überzeugt, mit neuen Technologien die Aufgabenstellungen zielgerichtet lösen zu können. Oftmals ist das aber eine auf keinerlei quantifizierbaren Erfahrungswerten beruhende Überzeugung.

Motivation ist häufig der Wunsch, mit einer neuen, interessanten, modernen Technologie zu arbeiten. Auch wenn sie vielleicht fortschrittlich und bewährt sind, so sind sie per se nicht immer zielgerichtet.

Nicht selten hat die Entscheidung für eine neue Technik oder der Wechsel einer Technologie großen Einfluss auf die Wirtschaftlichkeit. Nur ein Teil der Aufwände steckt in der Programmierung. Es entstehen Kosten für Weiterbildung. Dokumentation muss überarbeitet werden. Für den Betrieb sind ggfs. neue Lösungen notwendig. Eine Steigerung der Produktivität bei der Entwicklung ist nur dann zielgerichtet, wenn andere Bereiche nicht darunter leiden.

> Gute Programmierer, Architekten oder Tester erstellen Software, die nicht dem Stand der Technik entspricht.

Veraltete oder unpassende Technologien und Techniken werden eingesetzt, weil es "historische Gründe" gibt. "Historische Gründe" sind zwar eine valide Erklärung, aber keine Entschuldigung. Die Maßnahme, Software nachträglich auf den Stand der Technik bringen, verursacht Kosten. Da die Kosten in der Regel hoch sind, wird die Maßnahme nicht umgesetzt. Dem Management ist dabei oft gar nicht bewusst, dass sie durch diese Entscheidung ggfs. vertraglichen Anforderungen an die Software missachten. Sie riskieren Gewährleistungs- und Schadenersatzforderungen.

Software-Entwicklungsprojekte sind häufig gekennzeichnet durch einen eklatanten Mangel an nützlicher Dokumentation. Nützlich ist eine Dokumentation, wenn sie erklärt, was realisiert wurde. Wissen über die Software wird im Team geteilt. Es lohnt sich, dieses wertvolle Wissen zu sichern. Ein Wiki ist ein geeignetes Instrument, um dieses Wissen als Produktdokumentation bereitzustellen. Eine Produktdokumentation hat das Ziel, den Zustand und die Fähigkeiten eines Produktes so exakt wie möglich zu beschreiben.

> Der Ausdruck wiki kommt aus dem Hawaiischen, bedeutet so viel wie "schnell, flink".

Das Wiki ist wesentlicher Bestandteil des Gesamtkonzeptes von cards+. Inhalte lassen sich schnell ändern und erweitern. Mit nur einem Mausklick wechselt eine interessierte Person in den Editiermodus, wird zum Schreibenden. Änderungen werden von anderen interessierten Personen kontrolliert und gegebenenfalls geändert. Das Prinzip der vielen Augen vermeidet Fehler oder führt zu Diskussionen. Durch die Kommentarfunktion im Wiki können solche Diskussion transparent für alle interessierten Personen gemacht werden. Potentiell falsche Informationen werden durch einen Kommentar markiert und weisen interessierte Personen darauf hin, dass die markierte Information bis zur Klärung mit Vorsicht zu genießen ist. Sobald die Klärung herbeigeführt wurde - oft in Verbindung mit einer Änderung am Code - wird der Kommentar entfernt.

In Wikipedia werden Inhalte durch Quellen belegt. In einem Wiki mit einer Produktdokumentation ist Code ein Beleg für die Korrektheit von Inhalten. Egal, was in Studien, Konzepten, Anforderungen, etc. steht. Am Ende zählt nur, was die Software tatsächlich leistet. Der Code ist die Wahrheit.

Durch Domain-Driven Design (kurz DDD) haben Entwickler gelernt, die Software zu strukturieren. cards+ erfindet DDD nicht neu. cards+ ist ein Angebot, ein agiler Ansatz, um die Ergebnisse der Modellierung aus dem DDD in einem Wiki zu sichern. Die Bausteine von cards+ geben dem Wiki eine nachvollziehbare Struktur. Eine Struktur, die sich im Code wiederholt, mit Elementen aus der gemeinsamen Sprache.

Der Einsatz von Asciidoc ist ein weiterer wichtiger Bestandteil des Gesamtkonzeptes von cards+.

> Asciidoc ist eine leichtgewichtige Auszeichnungssprache für eine textbasierte Dokumentengenerierung. Eine Asciidoc-Datei kann wie Quelltext entwickelt und versioniert werden.

Mit Asciidoc und der include-Direktive ist es sehr einfach, Teile des Codes in die Produktdokumentation im Wiki einzubetten. Eine Spring-Boot-Anwendung mit Spring-Data-JPA für Persistenz und Spring-REST-Docs für die API-Spezifikation kann mit Code dokumentiert werden. Die Datei `application.yaml` zeigt die zentrale Konfiguration der Anwendung. Die Eigenschaften von JPA-Entitäten werden durch die annotierten Felder sehr gut beschrieben. Algorithmen, die nach den Prinzipen von Clean Code implementiert wurden, sind lesbar. API-Tests produzieren während ihrer Ausführung Asciidoc-Fragmente. Wie so eine code-nahe Produktdokumentation im Detail aussehen kann, zeigt das Github-Repository `demoscs`.

Das Ergebnis ist eine Produktdokumentation, die in einem großen Maß aus Code besteht. Code, der in der veröffentlichten Form tatsächlich als Teil der Software ausgeführt wird. Hinweise und Erläuterungen im Wiki erklären, warum es den Code gibt. Der Code selbst zeigt, wie die konkrete Lösung aussieht.

Besonders bemerkenswert ist, dass mit dem Code auch Kommentare der Entwickler im Wiki lesbar werden. Damit kann die Spezifikation von jeder interessierten Person überprüft werden. Durch das Einbeziehen des Codes in die Produktdokumentation wird sie prüfbar. Das schafft Qualität.

https://cardsplus.info

https://cardsplus.github.io/demoscs

https://github.com/cardsplus/demoscs

In dem Beitrag mit dem Titel "Shifting to Continuous Documentation as a New Approach for Code Knowledge" erklärt der Autor das Prinzip der kontinuierlichen Dokumentation. Er bezieht sich dabei auf andere Prinzipien, die in der modernen Software-Entwicklung nicht mehr wegzudenken sind. Mit _Continuous Integration_ bauen und testen wir unsere Software kontinuierlich mit dem Ziel, früh Fehler zu entdecken (fail fast). Wir liefern unsere Software häufig mit dem Ziel, sie in kleinen gut testbaren Schritten zu verändern und nennen es _Continuous Deployment_. Wir liefern die Software in kurzen Abständen mit dem Ziel, auf jeden Bedarf der Kunden und Nutzer sicher und schnell zu reagieren und nennen es _Continuous Delivery_. Warum dokumentieren wir unserer Software nicht auch kontinuierlich und nennen es _Continuous Documentation_?

> Continuous Documentation is the process that optimizes and reduces drift between the codebase and code-specific knowledge. Continuous Documentation applies the paradigm of automated integration of documentation into the development pipelines, by building and updating documentation incrementally, thereby keeping it in sync with the codebase. Continuous Documentation means that the Documentation is always up-to-date; Created when best and code-coupled.

https://www.infoq.com/articles/continuous-documentation/

---

Dokumentation ist keine Option bei der Entwicklung einer nicht trivialen Software.

Sie ist notwendig, um die gewünschte Geschwindigkeit bei der Realisierung neuer Funktionen zu erreichen, ohne die Qualität der Software insgesamt zu gefährden.

Dokumentation ist wichtiges Wissen. Selbst ein sehr gut lesbarer Code kann nur erklären, wie etwas funktioniert. Wer wann was mit der Software tut kann Code alleine kaum erklären.

Dokumentation sollte korrekt sein. Sie muss geprüft werden. Dafür muss sie prüfbar sein. Es muss Kritierien geben, um entscheiden zu können, ob etwas richtig oder falsch ist.

Dokumentation sollte vollständig sein. Dafür muss bekannt sein, was 100% bedeutet. Es muss ein definiertes Soll geben.

---

Dokumentieren ist ein kreativer Prozess. Er kann nicht komplett automatisiert werden. Ein Architekturbild muss auf den Punkt bringen, um was es geht. Es ist eine Visualisierung für das große Ganze, reduziert auf die Kernkomponenten. Eine Vision muss der Kunde verstehen. Sie muss in seiner Sprache geschrieben sein. Sie ist wichtiger Input für die Entwicklung.

Spezifizieren ist das Präzisieren von geforderten Fähigkeiten einer Software.

In einem agilen Entwicklungsprozess wird inkrementell spezifiziert. Jeder Fortschritt in der Implementierung führt zu einer Veränderung in der Spezifikation. Eine Spezifikation ist eine code-gekoppelte Dokumentation. Aufgrund der Nähe zum Code muss eine Spezifikation mit dem Code zusammen versioniert werden.

Für eine Spezifikation bietet sich `Asciidoc` als Format an. Eine Konfigurationsdatei oder jede Schemadatei für Json, Avro, Protobuf oder XML kann mit der `source`-Direktive direkt als Spezifikation verwendet werden. Sauberer Code, ausgeschnitten mit der `include`-Direktive von Asciidoc, oder Asciidoc-Fragmente, generiert mit Spring REST Docs, werden mit einer Überschrift und einen einführenden Satz versehen zur perfekten Beschreibung. Mit Asciidoc können Tabellen gestaltet werden, mit Daten aus einer CSV-Datei, die in einem CI-Job erstellt wird. Mit der Diagramm-Erweiterung von Asciidoc wird der Text ganz einfach um Grafiken ergänzt. Text mit Visualisierungen wirkt stärker. Gute Diagramme unterstützen das überfliegende Lesen.

https://docs.asciidoctor.org/asciidoc/latest/

---

Dokumentation ist wichtig und sollte nicht auf später verschoben werden.

Gute Dokumentation macht uns besser. Dokumentieren muss eine Aufgabe werden, die ohne zu zögern während der Entwicklung erledigt wird. Mit _Continuous Documentation_ ändern wir die Art und Weise, wie wir Spezifikationen erstellen und integriert in einer Produktdokumentation konsumieren. Wir folgen den Prinzipien der kontinuierlichen Verbesserung in den Dimensionen Code, Test und Spezifikation.

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.