Agile Entwicklungsmethoden haben sich aus der Erkenntnis entwickelt, dass sich Anforderungen für ein Produkt nie so exakt spezifizieren lassen, dass kein Spielraum für Interpretationen bleibt. Die Welt dreht sich während der Realisierung weiter. Was heute eine gute Idee ist, kann morgen schon ein alter Hut sein. Methoden wie Scrum setzen darum auf Feedback.

Produktverantwortliche, Entwickler, Tester und Nutzer reden regelmäßig miteinander. Scrum schafft den Rahmen mit Meetings wie Daily, Review oder Retrospektive. So können Missverständnisse frühzeitig ausgeräumt werden. Alle arbeiten auf ein gemeinsames Ziel hin, reden miteinander und wollen sich kontinuierlich verbessern. Feedback hat das Ziel der Verbesserung. Um etwas besser zu machen, muss man aber wissen, was gut ist.

« Was ist gut? »

In einem agilen Entwicklungsprozess mit Scrum legen alle beteiligten Parteien großen Wert auf eine nachvollziehbare Definition für ein fertiges Produktinkrement. Der Product-Owner kann damit die erreichten Ziele gegenüber seinen Auftraggebern darstellen. Das Scrum-Team muss bei ihrem Versprechen (englisch: commitment) auch diese Definition berücksichtigen. Mit individuellen Akzeptanzkriterien in jeder Story im Sprint und allgemeinen Fertigstellungskriterien (englisch: definition of done) entsteht so eine Art Leistungsvereinbarung zwischen Product-Owner und Scrum-Team. Die allgemeinen Fertigstellungskriterien legen u.a. den Grundstein für Automatisierung (z.B. Installation auf “Knopfdruck” oder Infrastruktur “as a Code”) und stellen die Betriebsführbarkeit des Produktes sicher. Ein Kriterium ist eine angemessene Produktdokumentation. Das ist gut.

Das Manifest agiler Software-Entwicklung schätzt funktionierende Software mehr als umfassende Dokumentation. Der Umkehrschluss, keine Dokumentation zu erstellen, ist jedoch falsch, aus vielen Gründen, auf die ich jetzt nicht näher eingehen will. Die Erstellung einer angemessenen Dokumentation ist die richtige Konsequenz.

« Was ist angemessen? »

Dokumentation am Beginn und am Ende eines Sprints unterscheidet sich. Am Beginn des Sprints ist umfangreiches Wissen notwendig, damit das Scrum-Team die richtige Lösung für die Story findet. Der Product-Owner erklärt die Anforderung. Das notwendige Wissen für die Realisierung durch das Scrum-Team wird im Refinement erarbeitet, indem Product-Owner und Scrum-Team gemeinsam Anwendungsfälle diskutieren und Sonderfälle akzeptieren oder ausschließen. Das Ergebnis wird als Story im Backlog dokumentiert und mit einer ersten Einschätzung der Komplexität versehen.

Dieses ohne Frage sehr wertvolle Wissen im Backlog zähle ich zur Projektdokumentation. Während des Sprints wird genau dieses Wissen verwendet, um die richtige Lösung zu realisieren. Wissen wird in erster Linie in Code, Spezifikationen und Konfigurationen transformiert. Das gleiche Wissen wird verwendet für die Erstellung ausführbarer Testfälle, organisiert in einer Testpyramide. Am Ende des Sprints ist der überwiegende Teil des Wissens aus der Story nun Teil des Produktes. Ein kleiner, für das Verständnis des Produktes wichtiger Teil muss jedoch als Produktdokumentation erhalten bleiben.

Eine Produktdokumentation ist immer ein Sprint-Ergebnis. Das Produkt wird im Sprint gezielt verbessert oder erweitert. Auch in der Produktdokumentation werden daher nur wenige Dokumente geändert oder neu erstellt. Angemessen bedeutet, dass jedes Dokument einen Zweck erfüllt und einen Wert für ihre Leser hat. Einen Wert haben sie aber nur, wenn sie richtig und vollständig sind.

« Was bedeutet richtig? »

Richtigkeit ist ein Ergebnis kontinuierlicher Verbesserung, getrieben vom Feedback aller Beteiligten, motiviert durch den bekannten Grundsatz für Retrospektiven, der gerne zitierten „prime directive“.

» Unabhängig davon was wir heute entdecken, verstehen und glauben wir aufrichtig, dass in der gegebenen Situation, mit dem verfügbaren Wissen und Ressourcen und unseren individuellen Fähigkeiten, jede(r) sein bestes getan hat. »

Norman L. Kerth

Ein Dokument ist richtig, wenn es von niemanden beanstandet wird. Durch den Einsatz eines Wiki besitzen wir ein sehr wertvolles Werkzeug: Die Kommentarfunktion. Sie versetzt jeden Leser in die Lage, jederzeit und ohne Hürden sein Feedback zu Fehlern oder Lücken in den Seiten zu geben. Moderierte Kommentare sind ein wichtiges Prinzip von CARDS+. Die Moderation durch die Autoren der Seiten sorgt dafür, dass Kommentare verschwinden, wenn sie erledigt wurden, weil

  • der Kommentar dazu geführt hat, dass die Seite durch den Autor korrigiert wurde.
  • der Kommentar eine Frage war, die der Autor klären konnte.
  • der Kommentar ist nach Analyse des Autors falsch.

Eine Seite im Wiki ist demzufolge richtig, wenn sie keine Kommentare enthält.

« Was bedeutet vollständig? »

Vollständigkeit ist das Ergebnis der Anwendung der Praktiken und Prinzipien von CARDS+. Mit den Bausteinen wird Dokumentation inkrementell erstellt. Man kann sagen, eine Produktdokumentation wird entwickelt. Beim Programmieren gibt es ungeschriebene Gesetze, die ohne weiteres auch auf das Dokumentieren angewendet werden kann. Mit der Initiative “Clean Code Developer”, begründet von Robert C. Martin, bekommen bewährte Praktiken und Prinzipien einen Namen, z.B. die Pfadfinderregel oder das Prinzip DRY, und eine greifbare Definition.

In Clean Code geht es nicht um Plattform oder Technologie oder ein Programmierparadigma. Es dreht sich vielmehr um das unter all dem liegende Substrat: Code als Quelltext und Code als strukturierter Ausdruck von Funktionalität. Für Code als kleinsten gemeinsamen Nenner zwischen Softwareentwicklern aller Coleur beschreibt Clean Code eine Menge von Prinzipien und Praktiken als kleinsten gemeinsamen Nenner.

Weiterlesen auf http://clean-code-developer.de/

Durch das Prinzip KISS konzentriert sich ein Autor auf das Wesentliche, versucht klar verständlich und einfach Sachverhalte zu beschreiben, nutzt Bilder. Mit dem Prinzip DRY achtet ein Autor darauf, jede Information nur einmal im Detail zu beschreiben. In der Konsequenz bedeutet das die direkte Verwendung von Code oder aus Code generierten Artefakten (z.B. ein Avro-Schema, ein XSD-File oder Swagger) im Wiki.

Am Anfang des Beitrages habe ich mich gefragt, was eine gute und angemessene Dokumentation ist. In erster Linie muss Dokumentation richtig sein. Und das ist gleichzeitig schon die größte Herausforderung. Autoren stellen sich dieser Herausforderung als Gemeinschaft und nutzen das Feedback aller Leser dazu, die Richtigkeit der Dokumente sicherzustellen. Es muss ein natürlicher Reflex jedes Lesers sein, einen Kommentar im Wiki zu hinterlassen, wenn er einen Fehler entdeckt. Eine Dokumentation sollte auch vollständig sein. Wenn jeder Entwickler die Produktdokumentation in seiner täglichen Arbeit verwendet und Feedback gibt, wenn er eine nicht dokumentierte Fähigkeit des System entdeckt, dann können die Autoren Lücken schnell schließen.

Feedback einfach so zu geben, ohne extra aufgefordert zu werden, muss ganz einfach Teil der Kultur in einer Projektorganisation sein.