Projektmanagement

Agile Dokumentation. TECH TALK mit Simon Krackrügge

Erfahren Sie, welche Anforderungen agile Softwareentwicklung an agile Dokumentation stellt

Agile Dokumentation mit Simon Krackrügge - TECH TALK

Agil ist weit mehr als ein Trend. Seit das Agile Manifest im Jahr 2001 das Licht der Welt erblickt hat, hat die agile Arbeitsweise eine beispielhafte Erfolgsgeschichte geschrieben. Da aber bei aller Flexibilität und Dynamik die Dokumention weiterhin wichtig bleibt, empfiehlt Simon Krackrügge eine agile Dokumentation.

Was ist eigentlich Agil?

Agil bedeutet, dass wir unsere Projekte nicht mehr stur nach einem anfangs gefassten Plan abwickeln. Es bedeutet, dass wir uns vielmehr auf Unwägbarkeiten einstellen und diese zulassen. Denn IT-Projekte sind wie Reisen: Egal, wie wasserdicht die Planung vor Reiseantritt erscheint, das Unerwartete geschieht.

Dies gilt insbesondere dort, wo die Technologien anspruchsvoll die Anforderungen komplex sind. Außerdem gibt es im laufenden Projekt auch fachliche Änderungswünsche, die beim Start noch nicht unbedingt abzusehen waren. Sei es, dass weitere Systeme angebunden werden müssen, sei es, dass die Nutzerlandschaft sich verändert hat oder dass weitere Dienste und Features zu integrieren sind: Die Liste der Eventualitäten ist lang.

Manifest für Agile Softwareentwicklung

Und so lautet das Manifest wörtlich:

„Wir erschließen bessere Wege, Software zu entwickeln, indem wir es selbst tun und anderen dabei helfen. Durch diese Tätigkeit haben wir diese Werte zu schätzen gelernt:

  • Individuen und Interaktionen mehr als Prozesse und Werkzeuge
  • Funktionierende Software mehr als umfassende Dokumentation
  • Zusammenarbeit mit dem Kunden mehr als Vertragsverhandlung
  • Reagieren auf Veränderung mehr als das Befolgen eines Plans

Das heißt, obwohl wir die Werte auf der rechten Seite wichtig finden, schätzen wir die Werte auf der linken Seite höher ein.“

Verfasser: Kent Beck, Mike Beedle, Arie van Bennekum, Alistair Cockburn, Ward Cunningham, Martin Fowler, James Grenning, Jim Highsmith, Andrew Hunt, Ron Jeffries, Jon Kern, Brian Marick, Robert C. Martin, Steve Mellor, Ken Schwaber, Jeff Sutherland, Dave Thomas. Erscheinungsjahr: 2001

http://agilemanifesto.org/iso/de/manifesto.html

… Und was ist dann Agile Dokumentation?

Hier setzt der TECH TALK von Simon Krackrügge an. Agile Methoden sind ja nicht von sich aus dokumentationsaffin. Sie sind im Gegenteil eher von Flexibilität geprägt und legen größeren Wert auf die spontane Handlungsfähigkeit innerhalb eines Projektes als auf dessen Dokumentation für die „Ewigkeit“. Entsprechend sind auch die Werkzeuge eher spontan: Zettel, Kanban-Boards, mündlicher Dialog.

Dokumentation bleibt aber weiterhin sehr wichtig. Denn Zettel, Dialoge und User Stories ersetzen einfach nicht die nachhaltige Speicherung von Wissen. Denn natürlich wollen wir dieses Wissen nicht nur simultan vermitteln, sondern auch über den engeren Wirkungskreis hinaus langfristig festhalten.

Die Vorteile nachhaltiger Dokumentation

  • Jeder kann sie in seinem Tempo lesen
  • Jeder liest sie dann, wenn er sich bestmöglich darauf konzentrieren kann
  • Die Teilhaberschaft ist insgesamt breiter

Wie verbinden wir also die Vorteile Nachhaltigkeit und Agilität in der Dokumentation?

Die Antwort lautet: Agile Dokumentation! Heißt: Wir dokumentieren bedarfsgerecht! Das gelingt uns, wenn wir uns im Vorfeld über die Leserschaft Gedanken machen – und darauf ausgerichtet Form und Inhalt wählen. So hängt beispielsweise die Beschreibung einer Software und ihrer Features oder die technische Detailtiefe davon ab, wer das Dokument am Ende liest. Denn weder wollen wir Leser der Fachseite mit technischen Einzelheiten quälen, noch die Leser aus dem IT-Bereich mit Überblicksdarstellungen vergraulen.

Wir fragen uns also „Wer liest das eigentlich? Und welche Informationen verspricht sich dieser Leser von der Lektüre?“ Das klingt banal, ist es aber nicht. Denn von der Leser-Zielgruppe hängt nicht nur ab, was, sondern auch wie wir es dokumentieren. Benutzerhandbuch ist nicht gleich Installationshandbuch ist nicht gleich Projektdokumentation.

Hier ein paar Beispiele 

Produktdokumentation: Diese geschieht mittels verschiedener Handbücher (Benutzerhandbuch, Betriebshandbuch, Online-Hilfe). Diese basieren in aller Regel auf den Formatvorlagen des Kunden und sind strengen Regeln unterworfen. Leserschaft: Je nach Handbuch die Nutzer, die Administratoren oder der Support einer Software

Systemdokumentation: Diese liefert eine Innensicht. Sie gibt Auskunft über Datenmodell, Architekturentscheidungen, Software- und UI-Design und hält Code-Kommentare fest. Leserschaft: Alle am Projekt beteiligten Stakeholder mit technischem Hintergrund

Projektdokumentation: Alles, was es zur Zielsetzung und zum Verlauf eines Projektes zu sagen gibt, wird hier festgehalten: User Stories, Epics, Backlogs, Use Cases. Leserschaft: Alle am Projekt beteiligten Stakeholder mit fachlichem Hintergrund

Prozessdokumentation: Hier geht es um die Frage nach dem Wie: Definition of Ready, Definition of Done, diverse Workflows auf Basis von Git, JIRA etc. Leserschaft: Projektmanagement, Entwicklungsmanagement

Tools für die Agile Dokumentation

Je nach Projekt und Zielsetzung der Dokumentationen können verschiedene Tools wertvolle Dienste leisten. In der agilen Dokumentation haben sich insbesondere Wiki-Systeme bewährt. Ihre Vorzüge:

  • Interaktivität: Wikis können interaktiv von verschiedenen Stakeholdern bearbeitet werden
  • Aktualisierung: Ein Wiki kann minimalinvasiv immer auf dem neuesten Stand gehalten werden
  • Kommentierung: Kommentarfunktionen erleichtern den Ablauf und die Dokumentation bei Entscheidungsprozessen
  • Verlinkung: Es lassen sich problemlos andere Wissensquellen verlinken/anbinden
  • Suche: Wikis verfügen zumeist über eine sehr gute Suchfunktion
  • Versionskontrolle: Es besteht jederzeit Einsicht in die Dokumentenhistorie
  • PDF-Generierung: Es lassen sich bei Bedarf PDF- oder Worddateien ziehen

Das Ergebnis: Die Dokumentationen zum Projekt können inkrementell verfasst werden. Am besten bindet man sie in sinnvollen Abständen als wiederkehrende Aufgabe in die Projektsprints mit ein (nicht ständig, damit man nicht voreilig dokumentiert). So werden sie etappenweise und projektbegleitend verfasst und können den Wechselfällen des Projektes optimal flexibel begegnen. Damit sind sie im besten Sinne agil.

Und noch ein wichtiges Gebot zur Lesbarkeit

Analog zum Clean Code in der Softwareentwicklung gibt es natürlich auch bei der Dokumentation einen ungeschriebenen Kodex, klar und sachlich zu schreiben. Insbesondere agile Dokumentation sollte den Lesernutzen kompromisslos in den Vordergrund stellen:

  • Verwende nur so viele Worte wie nötig und so wenige wie möglich
  • Strukturiere deinen Text
  • Nutze nur eindeutige Vokabeln und stelle dem Leser ein Glossar zu den verwendeten Begriffen zur Verfügung – gerne in Form eines Beipackzettels oder einer Gebrauchsanweisung
  • Mache es wie ein Pfadfinder und hinterlasse die Dokumentation (dort ist es die Natur) besser als du sie vorgefunden hast
  • Single Level of Abstraction: Vermische nie die Abstraktionsebenen
  • Single Responsibility Principle: Bleibe dem Ziel und Zweck deiner Dokumentation treu, eröffne keine Nebenschauplätze.

Darüber hinaus gilt: Ein Diagramm sagt mehr als tausend Worte. Allerdings nur dann, wenn es tatsächlich Aussagekraft hat und den Sachverhalt effizienter darstellen kann als Schriftsprache.

Definition of Agile Documentation

Ebenfalls analog zu der in der agilen Softwareentwicklung üblichen Definition of Ready und Definition of Done empfiehlt Simon Krackrügge für die agile Dokumentation deshalb eine Definition of Agile Documentation:

  • Hohe Qualität
  • Zielgruppengerechte Form
  • Konzentration auf das Wesentliche
  • Klarheit in der Formulierung
  • Dokumentation auch von Entscheidungsprozessen
  • Keine persönlichen Arbeitsunterlagen
  • Benennung eines Wiki Gardeners oder Document Owners

Fazit

Agile Softwareentwicklung enthebt uns nicht der Verantwortung zu dokumentieren. Aber mit den Mitteln der agilen Dokumentation lassen sich die scheinbaren Gegensätze Agilität und Nachhaltigkeit effizient vereinen.

(jw)

Simon Krackrügge

Simon Krackrügge

Projektmanager