Das Manifest für agile Softwareentwicklung legt in Punkt 2 ganz klar den Fokus auf funktionierende Software. In manchen Projekten wird dieser Wert ganz gern als Argument verwendet, dass in agilen Projekten nichts mehr dokumentiert werden muss. Das ist so nicht haltbar, weil das Manifest jeden Wert als Ganzes schätzt, nur halt die linke Seite höher als die rechte.

02 Wir sind agil

Die Frage nach dem Wert

In jeder agilen Methode wird ständig nach dem Wert eines Projektergebnisses gefragt. Wert für den Kunden zu schaffen ist wichtiger als einen Plan einzuhalten! Das gilt natürlich auch für die Produktdokumentation.

  • Benutzerhandbuch und Trainingsunterlagen haben einen hohen Wert für die Nutzer der Software.
  • Das Betriebshandbuch hat einen hohen Wert, weil der produktive Einsatz Unterlagen für Installation, Betrieb und Notfälle erfordert.
  • In der Systembeschreibung geht es konkret um den Versuch, das fachliche Produktwissen vollständig und widerspruchsfrei zu erfassen. Der Wert wird unterschiedlich eingeschätzt.
  • Eine Architekturdefinition hat gerade beim Start eines Projektes große Bedeutung. Kaum ein Auftraggeber wird akzeptieren, dass eine Architektur einfach so entsteht.
  • Ein Glossar wünscht sich jeder.

In vielen Fällen ist der Wert der Dokumentation zweitrangig, weil sie durch unternehmensweite Vorgaben und Richtlinien gefordert und damit ein notwendiges Projektergebnis ist.

Frühzeitig und als Entwurf in guter Qualität bereitgestellt ist ein Benutzer- oder Betriebshandbuch eine ausgezeichnete Ergänzung zur Systembeschreibung und liefert wertvolle zusätzliche Informationen für den Test der Software. Gleichzeitig wird auch die Qualität der Handbücher frühzeitig durch die Verwendung beim Testen der Software geprüft. Nach meiner Einschätzung eine ganz klare Win-Win-Situation!

Eine Aufgabe für alle

In phasen-orientierten Projekten definieren Experten der Fachabteilung und Business-Analysten mit Fachkonzepten das Produkt zunächst bis ins kleinste Detail. Die Entwickler realisieren das Produkt nach den Fachkonzepten, nachdem diese vom Auftraggeber abgenommen wurden. In der Praxis werden die Fachkonzepte von den Entwicklern quasi als Vorgabe gelesen und beim Programmieren in eine technische Lösungsdokumentation transformiert. Fachkonzepte und Lösungsdokumentation stimmen am Ende nicht immer überein.

Eine agile Projektorganisation will anders vorgehen. Die Entwicklung startet mit einer Vision, die schrittweise mit Storys in einem Backlog verfeinert wird. Durch Priorisierung werden zuerst die wichtigen Storys identifiziert und in einem Sprint gelöst. Speziell in Scrum wird sehr stark mit Mitteln der direkten Kommunikation gearbeitet. Auf eine fachliche Dokumentation kann verzichtet werden, sagen einige, und statt einer Lösungsdokumentation gibt es den lauffähigen und kommentierten Code.

Beide Ansätze sind Extrempositionen in der Dokumentation. Sowohl zu frühe, umfangreiche Dokumentation als auch keine Dokumentation ist im Sinn des Manifests für agile Entwicklung nicht angemessen. Was genau angemessen ist, kann nicht pauschal gesagt werden. Je komplexer Software ist, desto wichtiger wird Dokumentation. Code alleine beantwortet nicht alle Fragen, ersetzt auf keinen Fall eine Systembeschreibung oder eine Architekturdefinition.

Dokumente zu schreiben ist mit Sicherheit nicht die Lieblingsbeschäftigung eines Entwicklers. Dokumentieren wird sehr häufig als Aufgabe gesehen, die auch “später” von “anderen” erledigt werden kann. Da geht sehr viel Wissen verloren.

Beiträge zum Inhalt der Produktdokumentation sind klar definiert und im Sprint planbar. Die Pflege der Dokumente der Systembeschreibung und der Architekturdefinition hat einen Wert für das cross-funktionale Team. Dokumentieren ist wie das Programmieren und Testen eine Kernaufgabe für das cross-funktionale Team. Die Ergebnisse sind prüfbar, Reviews innerhalb des Teams sind möglich. Schließlich muss auch das Dokumentieren wie das Programmieren “erlernbar” sein, damit ein Team mit diesen Aufgaben auch wachsen kann.

Professionell Dokumentieren

Die Initiative “Clean Code Developer” für mehr Professionalität in der Software-Entwicklung ist ein von mir persönlich geschätzter Katalog von Prinzipien und Praktiken, die uns zu “professionelleren” Entwicklern machen sollen. Ich behaupte, dass sich viele der Prinzipien und Praktiken ganz leicht auch auf das Dokumentieren anwenden lassen.

  • Wir schreiben Text für Layouts und Cases bzw. Stories in der Sprache unseres Kunden wie wir “Programmtexte” in Sprachen schreiben, die Computersysteme verstehen.
  • Wir wenden das Prinzip “Keep it simple, stupid” (KISS) der Programmierer an, damit Inhalte im Wiki nicht zu schnell verderben.
  • Wir wenden das Prinzip “Don´t Repeat Yourself” (DRY) der Programmierer an, um die Inhalte im Wiki weitestgehend frei von Redundanzen zu halten. Das Prinzip motiviert uns auch, Stichworte und Begriffsdefinitionen in einem Glossar zu verwenden.
  • Wir wenden die Pfadfinderregel an und führen Reviews durch, um die Qualität unserer Dokumentation laufend zu verbessern.
  • Wir nutzen das Prinzip “Separation of Concerns” (SOC), indem wir fachliche und technische Belange klar voneinander trennen.
    • Topic, Epic und Case dienen ausschließlich der fachlichen Beschreibung.
    • Layouts verwenden wir nur für die Spezifikation der Benutzeroberfläche (Zielgruppe Entwickler). Layouts werden außerdem vor der Realisierung geschrieben.
    • das Benutzerhandbuch (Zielgruppen Tester und User) verwenden wir nur für die Beschreibung der Verwendung der Benutzeroberfläche. Wir erstellen das Benutzerhandbuch, wenn die Realisierung abgeschlossen ist.
    • das Betriebshandbuch (Zielgruppen Tester und Operatoren) nutzen wir für nur für die technischen Aspekte der Software.
  • Genau so wichtig wie “Source Code Conventions” für Code sind die Regeln und Vorlagen zur Erstellung von Inhalten im Wiki.
    • Wir definieren klare Regeln für den Aufbau jedes Artefaktes.
    • Wir unterstützen die Autoren durch Vorlagen für jedes Artefakt.
    • Handbücher unterliegen teilweise noch strengeren Richtlinien.
  • Das Prinzip des “Single Level of Abstraction” (SLA) fördert wie bei Code die Lesbarkeit von Inhalten im Wiki.
    • Autoren können sich auf eine konkrete Aufgabenstellung konzentrieren.
    • Reviewer können Inhalte effizienter prüfen.
  • Das Prinzip “Single Responsibility Principle” (SRP) verwenden wir hier leicht abweichend für die eindeutige Zuordnung eines Artefaktes im Wiki zu einer Rolle. Dadurch erreichen wir, dass Inhalte besser auf den Bedarf im Projekt abgestimmt sind.

Fazit

Wirklich erfolgreich können wir Agilität nur in einem cross-funktionalen Team einsetzen, in dem nicht nur programmiert und getestet, sondern auch dokumentiert wird. Mit Feedback und durch konsequente Durchführung von Reviews können wir sicherstellen, dass Analysten das beschreiben, was die Entwickler und Tester für ihre Arbeit im Sprint brauchen. Ein Prozess schafft Wert, wenn eine Dokumentation zu jeder Zeit erweitert oder korrigiert wird. So ein Prozess bildet eine sehr gute Grundlage für eine nachhaltige Produktdokumentation.