Eine bekanntes Mantra scrum-basierter Vorgehensmodelle der Software-Entwicklung ist, dass nur soviel dokumentiert wird wie notwendig ist für das Erreichen der Ziele. “So viel wie notwendig” ist natürlich ein dehnbarer Begriff. Eine vergleichbare Empfehlung hat das agile Manifest, indem es funktionierende Software höher bewertet als umfangreiche Dokumentation. In manchen Projekten wird diese Empfehlung als Rechtfertigung verwendet, fast nichts mehr zu dokumentieren. Und das Wenige, das doch aufgeschrieben wird, kann sehr oft nur von den Personen genutzt werden, die diese Dokumentation erstellt haben.

Auf der anderen Seite gibt es Projekte, die Unmengen von Wissen sammeln und ablegen. Oft fehlt ein klares Konzept, um mit der Informationsflut umzugehen. Über die Zeit entsteht so eine völlig inhomogene Sammlung unterschiedlichster Arbeitsdokumente. Kaum jemand ist in der Lage, eine Einschätzung zur Qualität dieser Dokumente abzugeben.

07 Was bedeutet nachhaltig dokumentieren

Leitlinien

In den bisherigen Artikeln habe ich mich im Zusammenhang mit der Erstellung und Pflege der Dokumentation in einem agilen Projekt mit den Fragen beschäftigt, welche Zielgruppen unsere Dokumentation hat, warum wir eindeutige Begriffe in unserer Kommunikation brauchen und was eine redundanzfreie Ablage von Dokumenten ist.

Jetzt möchte ich mich um das große Ganze, also um das sogenannte “Big Picture” der Methode kümmern. Meine persönlichen Leitlinien für den Entwurf der Dokumentenstruktur sind

  1. Nachhaltig
  2. Ganzheitlich
  3. Vollständig
  4. Prüfbar

Sie helfen mir bei der Beurteilung der Angemessenheit einer Dokumentation, wie sie im agilen Manifest gefordert wird.

Nachhaltig

Suche ich im Internet nach dem Begriff “nachhaltig”, erhalte ich neben Wikipedia und Duden Treffer aus vielen unterschiedlichen Bereichen, meist jedoch mit wirtschaftlichem Hintergrund. Nachhaltig im wörtlichen Sinn heißt “hält eben lange nach” oder “das was du tust, wirkt lange nach”.

Nachhaltigkeit ist ein Handlungsprinzip zur Ressourcen-Nutzung, bei dem die Bewahrung der wesentlichen Eigenschaften, der Stabilität und der natürlichen Regenerationsfähigkeit des jeweiligen Systems im Vordergrund steht.
wikipedia

Nachhaltigkeit im Zusammenhang mit einer Produktdokumentation steht für mich für das Bestreben, Wissen über ein Produkt permanent zu sammeln und für alle Zielgruppen verfügbar zu machen. Es geht um das Versprechen, jede Änderung am Produkt bekannt zu machen, zu veröffentlichen. Nachhaltig dokumentieren bedeutet sofort zu dokumentieren, also die Aufgabe nicht auf später zu verschieben.

Nachhaltig in einem anderen Sinn bedeutet, dass die von uns erstellte Produktdokumentation robust gegenüber vielen Veränderungen ist, z.B.:

  • Der Kunde ist erfolgreich und will das Produkt stärker einsetzen, die Anzahl der Nutzer und/oder das Mengengerüst der Daten erhöhen sich.
  • Der Auftraggeber wechselt und verfolgt neue Ziele mit dem Produkt, verbunden mit neuen Anforderungen, z.B. mit einer neuen Lösung für mobile Endgeräte.
  • Im Unternehmen ändern sich Geschäftsprozesse, es gibt neue oder veränderte Anwendungsbereiche, in denen das Produkt eingesetzt werden soll.
  • Die Projektorganisation ändert sich, wir wenden eine neue Methode an (“Wir werden agil”) oder verändern die Team-Größe (größer oder kleiner).
  • Die Weiterbildungsstrategie des Unternehmens führt dazu, dass langjährige Mitarbeiter das Projekt verlassen müssen/wollen.
  • Neue Technologien sollen oder müssen eingesetzt werden, eine Bibliothek oder Middleware ist nicht mehr verfügbar, wird nicht mehr gewartet, passt nicht ins strategische Konzept oder ist schlicht zu teuer geworden.

Eine Produktdokumentation ist dann nachhaltig, wenn sie trotz dieser Veränderungen weiterhin nutzbar ist.

Eine nachhaltige Dokumentation verfolgt auch das Ziel, die Stärken der Mitarbeiter im Team zu nutzen und Schwächen durch individuelles Training auszugleichen. An der Dokumentation arbeiten alle im Team, jeder im Projekt trägt unabhängig von seiner Rolle einen wichtigen Teil zum Gesamterfolg bei! Es gibt eine Kultur im Team, in der die Regeln und die vorgegebene Struktur positiv empfunden werden, in der die laufende gegenseitige Prüfung der Qualität eine Selbstverständlichkeit ist und als Chance verstanden wird, sich persönlich weiter zu entwickeln. Denn nur was im Team begrüßt wird, hält auch lange nach!

Ganzheitlich

Vor allem bei Projekten mit vielen Releases oder mit langer Laufzeit ist besonders wichtig, dass die Dokumentation von jeder Person im Team gepflegt werden kann, d.h. die Fähigkeit zur Pflege muss in einem cross-funktionalen Team genauso verfügbar sein wie die Fähigkeiten zum Programmieren oder Testen. Jeder im Team muss sich des Wertes der Dokumentation für seine Arbeit bewusst und persönlich motiviert sein, die Dokumentation zu erweitern, zu erhalten und zu verbessern. Der Ansatz ist also ganzheitlich.

Die Betrachtung und Behandlung eines Themas, eines Gegenstandes oder einer Beziehung in seiner Ganzheit bedeutet eine umfassende, weitsichtige und weit vorausschauende Berücksichtigung möglichst vieler Aspekte und Zusammenhänge.wikipedia

Eine ganzheitliche Dokumentation stellt den Versuch dar, eine Domäne in allen Facetten darzustellen.

  • Wir stellen die Fragen nach den Ursprüngen (“Wer hat den Bedarf?”) und den Zielen.
  • Wir legen Rahmenbedingungen fest und erfassen Regeln, Werte und Normen.
  • Wir bestimmen die Auswirkungen eines Problems und wägen den Nutzen der Lösung ab und bewerten absehbare Reaktionen anderer im Umgang damit.
  • Wir analysieren Neben-, Folge- und Wechselwirkungen des Systemverhaltens und entwickeln daraus weitere Anwendungsaspekte als zusätzlichen Wert.
  • Wir beschreiben Eigenschaften, direkte und indirekte Beziehungen und Querbeziehungen von Objekten der Domäne.

In diesem Versuch ziehen wir keine Grenzen zwischen fachlicher und technischer Spezifikation. Wir fördern eine gemeinsame Sprache im Team und im Projekt. Mit einem Glossar und einem Fachklassenmodell prägen wir eindeutige Begriffe, die wir auch noch Jahre später kennen und wissen, was sie bedeuten.

Vollständig

Wir beschränken uns nicht auf das Wiki. Code verstehen wir als wichtige Dokumentation, frei nach dem Motto “im Code steckt die Wahrheit”. Wir nutzen das Konzept einer Link-Sammlung, um Dokumente außerhalb des Wiki einzubeziehen. Dazu zählen vertragsrelevante Dokumente, die in einer revisionssicheren Ablage gespeichert werden, und Normen oder Spezifikationen von Partnersystemen, die für unser Produkt eine Rolle spielen.

Die vollständige Dokumentation befindet sich in verschiedenen Medien:

  1. In einem Anforderungsmanagementsystem
    • Bedarf der Stakeholder
    • Funktionale Anforderungen
    • Nicht-funktionale Aspekte
    • Qualitätsmerkmale
  2. In einem Dokumentenmanagementsystem
    • Vertragsrelevante Dokumente
    • Normen und Spezifikationen
    • Schnittstellenvereinbarungen
    • Ergebnisdokumente (Baselines)
    • Handbücher
  3. In einem Wiki (z.B. Confluence)
  4. In einem Repository
    • Code
    • Kommentare  (z.B. Javadoc)
    • Skripte
    • Schemadefinitionen
    • Konfigurationsdateien
    • Akzeptanztests
    • Integrationstests
  5. In einem Workflow-Tool (z.B. JIRA)
    • Epics und Stories für die Umsetzung
    • Tickets für Defektbehebung

Es gibt eine sehr starke Abhängigkeit zwischen nachhaltiger und vollständiger Dokumentation. Auf lange Sicht erreichen wir eine vollständige Dokumentation nur dann, wenn unsere Ergebnisdokumente nicht verderben. Mit anderen Worten müssen wir es schaffen, dass viele Bereiche, die aus Sicht des Kunden stabil sind, auch stabil hinsichtlich der Dokumentation sind.

Prüfbar

Eine vollständige Dokumentation muss aber auch als solche erkennbar sein. Wir brauchen daher prüfbare Regeln für den Aufbau und Inhalt aller Ergebnisdokumente in einer klar kommunizierten Struktur! Eine gute Struktur gibt vor, wo die Grenzen sind, d.h. was gehört in einen Baustein und was nicht. Diese Abgrenzung ist sehr wichtig.

Weniger ist mehr! Gemeint ist, dass bei der Gestaltung eines Textes, Designs oder Entwurfs die Reduzierung auf das Wesentliche oft zu einem besseren Ergebnis führt als die Überfrachtung mit sehr detailliertem Beiwerk.wikipedia

Die Reduktion auf das Wesentliche und Notwendige gilt vor allem auch bei der fachlichen Analyse für Software-Systeme. Sie soll dort aufhören, wo dem Entwickler klar ist, wie die Lösung im Rahmen der technischen Architektur aussehen muss. Jede weitere fachliche Detaillierung vergeudet nur Zeit und schafft sogar Widersprüche, wenn der Analyst nicht die letzten Details der technischen Lösung kennt.