Über unsMediaKontaktImpressum
Robert Bruckbauer 11. August 2015

Agile Dokumentation für Stakeholder und Projektmitarbeiter

Dokumentation ist ein Thema in jedem Projekt. Abhängig vom Vorgehensmodell – agil, iterativ oder ganz klassisch mit Wasserfall – entstehen Lastenhefte, Pflichtenhefte, Studien, Grob- und Fachfeinkonzepte, fachliche und technische Spezifikationen, Richtlinien, Anleitungen, Entscheidungen, Vorgaben, Skizzen, Handbücher, um nur die bekanntesten Begriffe zu nennen. Die Zielgruppen, für die diese Dokumente erstellt werden, sind so unterschiedlich wie die Ziele, die mit der Dokumentation erreicht werden sollen. In einem agilen Umfeld muss die Tätigkeit des Dokumentierens eine Aufgabe im cross-funktionalen Team sein. Wir müssen beim Dokumentieren die gleichen Werte vertreten wie beim Programmieren und Testen der Software. Die Inhalte der Systembeschreibung und die Handbücher müssen die gleichen Qualitätsansprüche erfüllen wie programmierter Code.

In diesem Artikel, eine Zusammenfassung aus meinem Blog "Real World Scrum" [1], möchte ich eine agile Methode für Wissensmanagement in einem agilen Projekt beschreiben. Bei dieser Methode geht es vorrangig um die Erstellung und Pflege von fachlichen Inhalten zur Sicherung von Wissen in einem Wiki. Die Methode

  • gibt ein Wissensmodell mit klar definierten Strukturen vor,
  • legt Regeln fest, die es dem Team ermöglichen, die geforderte Qualität sicherzustellen,
  • formuliert Praktiken, durch die wir wichtige Informationen von weniger wichtigen unterscheiden können und
  • fordert Werkzeuge, die es uns erlauben, schnell und effektiv einmal erarbeitetes Wissen zu sichern.

Das Wissen befindet sich in den Köpfen unserer Mitarbeiter und in ganz vielen Dokumenten. Wissen, das wir mit unserer Methode sammeln und strukturiert als eine Dokumentation bereitstellen.

Diese Dokumentation dient als mentaler Anker für Informationen im Projekt mit einem nachhaltigen Wert für alle Zielgruppen.

  • Wir sichern Wissen auf lange Zeit mit hoher Qualität.
  • Wir beschränken uns auf das Wesentliche und Notwendige.
  • Wir dokumentieren die Ergebnisse von Diskussionen.
  • Wir vermeiden persönliche Arbeitsunterlagen!
  • Wir definieren Grenzen: Was muss sein, was brauchen wir nicht.
  • Wir unterscheiden flüchtige und dauerhafte Informationen.

Dokumentation trägt zum Erhalt des Überblicks über das Produkt bei und fördert ein gemeinsames Verständnis für Probleme und deren Lösungen.

  • Wir vermitteln ein "Big Picture" für alle Zielgruppen.
  • Wir etablieren eine gemeinsame Sprache im Projekt.
  • Wir pflegen von Anfang an ein Glossar.
  • Wir pflegen externe Quellen in einer Linksammlung.
  • Wir legen einen allen im Team bekannten Weg zum Erfassen von Inhalten fest.
  • Jede Information ist dort, wo sie sein soll – und nur dort!
  • Wir verbessern uns laufend.

Wo volle Flexibilität verlangt ist, braucht es möglichst vollständige und zuverlässige Information. Deswegen ist es in agilen Projekten wichtig, dass diejenigen, die dokumentieren, von Anfang an Teil des cross-funktionalen Teams und damit verantwortlich für die Erstellung und Sicherung des Wissens über das Produkt sind.

  • Wir sind flexibel bei Änderungen an der Vision des Produktes.
  • Wir zerlegen die Aufgaben im Projekt in "handliche Portionen".
  • Wir sind robust im Zusammenhang mit nicht-funktionalen Anforderungen.

Wer schon einmal in ein Projekt eingestiegen ist, das längere Zeit auf "Sparflamme" gewartet wurde, weiß den Wert der Dokumentation schätzen – aber nur, wenn die Qualität gut und der Inhalt glaubwürdig ist. In allen anderen Fällen ist Dokumentation mehr Fluch als Segen.

In der agilen Methode Scrum ist die Verwendung von Epics und User-Stories für die Bereitstellung von Informationen für den Prozess der Entwicklung bereits fest verankert.

Eine User-Story kann Wissen zwar sehr effizient vermitteln, aber das Wissen wird nicht in einer nachhaltigen Form gespeichert.

Epics und User-Stories sind für die Realisierung einer Software unabdinglich. Aber User-Stories sind häufig aufeinander aufbauend, sie beschreiben quasi einen Weg. Es fehlt die konsolidierte Form der User-Story, die es uns später noch erlaubt, die Umsetzung nachzuvollziehen. Die Beschreibung in einer User-Story "verdirbt" recht schnell.

In der klassischen Anforderungsanalyse in nicht-agilen Projekten werden Usecases immer noch sehr gerne verwendet. Mit der Verwendung von Usecases unternehmen wir den Versuch, das Wissen sehr strukturiert und umfassend bis ins letzte Detail zu beschreiben. Ein Usecase ist agil nur sehr schwer umsetzbar und in den meisten Fällen einfach zu groß, um ihn in einem Sprint umzusetzen. Die aktuelle Weiterentwicklung mit dem Titel "Usecase 2.0" ist eine wesentliche Verbesserung. Die Grundidee der Aufteilung eines Usecase in basic, alternative bzw. exception flows und slices findet sich daher in abgewandelter Form auch in der vorliegenden Lösung wieder.

Was sind die Rahmenbedingungen?

Zur Illustration der Ideen und Lösungen ist es hilfreich, bestimmte Vorgaben und Annahmen für ein Projekt mit einer gewissen Größe und Struktur zu treffen. Stellen Sie sich daher ein Projekt vor, das für die Entwicklung eines rechnergestütztes Betriebsleitsystems eines Eisenbahnverkehrsunternehmens verantwortlich ist. Dieses System hat sechs Partnersysteme mit technischen Schnittstellen. Die Anwendung besteht aus einem Arbeitsplatz mit grafischer Benutzeroberfläche, einem Werkzeug zur Stammdatenpflege, einem Langzeitarchiv mit einem Berichtswesen, einer mobilen App für das Personal und für die Fahrgäste. In diesem Projekt hat der Auftraggeber festgelegt, dass für jedes Release die Software in einer vom Unternehmen festgelegten Form zu liefern ist. Zusätzlich zur Software fordert der Auftraggeber für jedes Release der Software folgende Unterlagen:

  1. Release-Notes inkl. Change-Log (englisch)
  2. Betriebshandbuch (englisch)
  3. Benutzerhandbuch (deutsch)
  4. Trainingsunterlagen (deutsch)
  5. Systembeschreibung (deutsch)
  6. Architekturdefinition (englisch)

Wichtig ist noch der Hinweis auf die Sprache der Unterlagen. Im Projekt ist festgelegt, dass jedes Dokument dauerhaft nur in der festgelegten Sprache geschrieben wird. Das ist hauptsächlich darin begründet, dass der Aufwand zur Pflege der Inhalte in zwei Sprachen in gleicher Qualität vom Auftraggeber nicht bezahlt wird.

Die Frage nach den Zielgruppen für das Wiki lässt sich einfach beantworten: Alle, also Stakeholder, Product-Owner, Scrum-Master, Analysten, Architekten, Entwickler, Tester, Operatoren und Power-User. Eine Zielgruppe hat entweder fundamentales Wissen zum Einsatz des Produktes oder benötigt Wissen über das Produkt, um Tätigkeiten im Rahmen des Projektes durchzuführen.

Wir sind agil!

Für die Projektorganisation ist Scrum als agiles Vorgehensmodell etabliert. Ich möchte die Aspekte der Entwicklung und des Tests nur soweit beleuchten, wie es für die Erläuterungen der Ideen und Lösungen für die Dokumentation notwendig oder hilfreich ist.

Wir wollen schlanke Prozesse und Strukturen ("lean"), wir begrüßen Änderungen und fokussieren uns auf das Notwendige ("agile").

Das Manifest für agile Softwareentwicklung [2] 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. In der agilen Methode soll ständig nach dem business value gefragt werden. Das gilt auch für die hier beschriebene Dokumentation.

  • Das Benutzerhandbuch hat einen hohen Wert, weil es vom Auftraggeber explizit gefordert wird.
  • Das Betriebshandbuch hat bei uns einen hohen Wert, weil der produktive Betrieb der Software aus dem Projekt organisatorisch ausgegliedert ist und entsprechende Unterlagen für den Betrieb zwingend erforderlich sind.
  • In unserem Fall ist der Wert der Systembeschreibung und der Architekturdefinition zweitrangig, weil beide Arten der Dokumentation durch unternehmensweite Vorgaben und Richtlinien gefordert und damit ein notwendiges Ergebnis des Projektes sind.

Über die Notwendigkeit, diese Unterlagen zu erstellen und zu pflegen, wurde bei der Einführung der agilen Methode im Projekt auch gesprochen. Der Auftraggeber hat aber klar gemacht, dass diese Ergebnistypen nicht verhandelbar sind. Wir konnten uns nur dahingehend einigen, dass wir den Aufwand für die Erstellung reduzieren wollen und der Auftraggeber uns dazu einen entsprechenden Spielraum gewährt. 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 Information 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!

Besonders wichtig in unserem agilen Umfeld ist es, die Tätigkeit des Dokumentierens als Aufgabe in das cross-funktionale Team zu bekommen.

Die Pflege der Systembeschreibung hat einen Wert für das cross-funktionale Team! Die Inhalte der Systembeschreibung sind klar definiert, um die Aufgaben zur Pflege der Seiten im Wiki im Sprint planbar zu machen. Die Aufgaben müssen prüfbar sein, damit Reviews innerhalb des Teams ermöglicht werden. Schließlich muss das Dokumentieren "erlernbar" sein, damit das Team mit diesen Aufgaben auch wachsen kann. Dokumentieren betrachten wir wie das Programmieren und Testen als Aufgabe für das cross-funktionale Team.

Die Initiative "Clean Code Developer" [3] für mehr Professionalität in der Softwareentwicklung ist ein von mir persönlich geschätzter Katalog von Prinzipien und Praktiken, der 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" 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, Feature und Case dienen ausschließlich der fachlichen Beschreibung.
    • Layouts verwenden wir nur für die Spezifikation der Benutzeroberfläche (Zielgruppe Entwickler).
    • Das Benutzerhandbuch (Zielgruppen Tester und User) verwenden wir nur für die Beschreibung der Verwendung der Benutzeroberfläche.
    • Das Betriebshandbuch (Zielgruppen Tester und Operatoren) nutzen wir nur für die technischen Aspekte der Software.
  • Genauso 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.

Wirklich erfolgreich können wir die Prinzipien und Praktiken nur in einem cross-funktionalen Team einsetzen, in dem nicht nur programmiert und getestet, sondern auch dokumentiert wird. Nur 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, der eine Erweiterung der Systembeschreibung während Entwicklung und Test erlaubt, schafft darum einen großen Wert und bildet die Grundlage für eine nachhaltige Systembeschreibung.

Redundanzfreie Ablage

Es ist schon sehr herausfordernd, alle wesentlichen Informationen zum Produkt über den gesamten Lebenszyklus einer Software zu sammeln, zu aktualisieren und strukturiert zu speichern. Ich gehe dabei von einem erfolgreichen Produkt aus, das viele Jahre existiert und laufend fachlichen und technischen Änderungen unterliegt. Durch Fluktuation oder durch Änderungen in der Organisation des Unternehmens entsteht außerdem ein regelmäßiger Wechsel der Mitarbeiter im Projekt und bei den Stakeholdern.

Der Begriff Ablage ist abstrakt. Code ist in einem Repository. Die Systembeschreibung befindet sich im Wiki. Für Anforderungen, Testpläne und Testfälle gibt es maßgeschneiderte Management-Tools. Epics, User-Stories und Defekte verfolgen wir in Workflow-Tools. Eines der wohl wichtigsten Ziele unserer Methode ist die redundanzfreie Ablage von fachlichen und technischen Inhalten in allen Ablagen für alle Zielgruppen. Wir müssen verhindern, dass eine Änderung an einer Stelle dazu führt, dass Informationen an einer anderen Stelle widersprüchlich dazu sind.

Redundanzfrei heißt in diesem Zusammenhang, dass jede Information nur einmal vorhanden ist.

Redundanzfreie Ablage bedeutet auch, dass die Dokumentation dort ist, wo sie auch gut gepflegt werden kann. Wo genau der richtige "Ablageort" ist, hängt ganz wesentlich vom Artefakt selbst ab. Auch Abhängigkeiten zwischen Seiten im Wiki müssen gut erkennbar sein.

Der Vorschlag für die neue Dokumentenstruktur unterstützt diese Ziele. Durch die Struktur kann jede Information eindeutig einem Artefakt zugewiesen werden. Jedes Artefakt:

  • hat klare Regeln, welcher Inhalt in einem Artefakt zu erfassen ist und welcher Inhalt nicht in ein bestimmtes Artefakt gehört;
  • hat klare Regeln zum Grad der Detaillierung des Inhaltes;
  • hat klare Regeln, wie Inhalte werkzeug-übergreifend verknüpft werden;
  • hat klare Regeln, welche Inhalte nicht verknüpft werden;
  • hat ein festgelegtes Medium (Datenformat und Werkzeug);
  • hat einen ganz bestimmten Ort in der Struktur;
  • hat einen eindeutigen Besitzer in Form einer Rolle.

Ein sehr positiver Nebeneffekt ist, dass wir durch die Regeln und die Struktur automatisch fachliche und technische Inhalte in kleinere, besser überblickbare Portionen zerlegen. Das lässt uns weitestgehend konfliktfrei an vielen Seiten im Wiki gleichzeitig arbeiten.

Eindeutige Begriffe

Ein weiterer sehr wichtiger Aspekt einer guten Dokumentation ist die klare Definition und Verwendung von Begriffen – fachlich und technisch. In einem komplexen Umfeld kommt es sehr oft zu der Situation, in der wir unterschiedliche Ausdrücke für den gleichen Begriff in der Systembeschreibung verwenden, um damit unterschiedliche Zielgruppen besser zu erreichen. In der technischen Umsetzung müssen wir uns jedoch für einen Begriff entscheiden. Bei der Wahl der Begriffe ist es wichtig, die Sprache der Nutzer des Systems und der Fachabteilungen zu berücksichtigen. Das Problem des "Überladens" von Begriffen bekommen wir durch die Einführung eines Glossars in den Griff. Wichtig ist aber, dass dieses Glossar vor allem von den Stakeholdern konsequent verwendet wird. Das ist nicht immer leicht, weil es oft regionale Unterschiede bei der Bezeichnung von Begriffen in den verschiedenen Fachabteilungen gibt (z. B. Ereignis). Das Projekt muss trotz der immer wieder massiv auftretenden Widerstände darauf drängen, dass sich alle Fachabteilungen auf einen Begriff im Glossar festlegen. Und der beste Weg, die Fachabteilungen auf den Begriff "einzuschwören" ist die konsequente Nutzung der Begriffe in allen Workshops mit den Stakeholdern und in der Systembeschreibung.

Das Glossar ist ein wichtiger Teil der Systembeschreibung und muss aktiv gepflegt werden.

Darum ist es wichtig, bereits in der Analyse einer fachlichen Anforderung die wichtigsten Begriffe zu identifizieren und sofort im Glossar zu erfassen. In den Reviews achten wir unter anderem auf die konsequente Nutzung dieser besonderen Worte aus dem Glossar in Texten.

Bei der Verwendung eines Wiki zur Dokumentation empfehlen wir, die Begriffe konsequent mit dem Glossar zu verlinken. Die Vorteile dieser Praxis sind:

  1. Durch den Link wird der Begriff automatisch hervorgehoben.
  2. Der Leser kann sich durch Klick auf den Link sofort den Begriff erklären lassen.
  3. Es gibt die Möglichkeit, alle Seiten zu suchen, die exakt diesen Begriff enthalten.

Das Fachklassenmodell beschränkt sich auf die fachlich relevanten Klassen und stellt neben dem Glossar ebenfalls eine sehr wichtige Quelle für eindeutige Begriffe dar. Eine Fachklasse beschreibt sehr genau einen wichtigen Begriff der Domäne.

Nachhaltig dokumentieren

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

  1. Nachhaltigkeit
  2. Ganzheitlichkeit
  3. Vollständigkeit

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. [4]

Nachhaltig in meinem Sinn bedeutet, dass die von uns erstellte Dokumentation 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 oder einer neuen Präsentation (z. B. mobiler Inhalt).
  • Im Unternehmen ändern sich Geschäftsprozesse, es gibt neue oder veränderte Anwendungsbereiche, in denen das Produkt eingesetzt werden soll.
  • Die Projektorganisation ändert sich.
  • 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 nachhaltige Dokumentation verfolgt auch das Ziel, die Stärken der Mitarbeiter im Team zu nutzen und die Schwächen zu trainieren. 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. Die laufende gegenseitige Prüfung der Qualität ist eine Selbstverständlichkeit und wird als Chance verstanden, sich persönlich weiterzuentwickeln. Denn nur was im Team begrüßt wird, hält auch lange nach!

Vor allem bei Projekten mit vielen Releases oder mit langer Laufzeit ist es besonders wichtig, dass die Dokumentation von jeder Person im Team gepflegt werden kann. Das heißt, 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.
[5]

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, 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, prägen eindeutige Begriffe, die wir auch noch Jahre später kennen und wissen, was wir damals meinten. Wir beschränken uns nicht auf das Wiki. Das bedeutet im Speziellen, dass wir neben Inhalten im Wiki auch die Kommentare im Code selbst als Dokumentation verstehen. Mit geeigneten Werkzeugen wird diese Informationsquelle für jeden im Projekt verfügbar gemacht. Die vollständige Dokumentation befindet sich in verschiedenen Medien:

  1.  In einem Anforderungsmanagementsystem
     - Bedarf der Stakeholder
     - Anforderungen an das System
  2. In einem Dokumentenmanagementsystem
     - Vertragsrelevante Dokumente
     - Schnittstellenvereinbarungen
     - Ergebnisdokumente (Baselines)
     - Handbücher
  3. Als Pages in einem Wiki (z. B. Confluence [6])
     - Systembeschreibung
     - Architekturdefinition
  4. In Form von Kommentaren (z. B. Javadoc [7]) im Code
     - Datenstrukturen
     - Datenflüsse
     - Algorithmen
  5. Als Issues in einer Vorgangsverwaltung (z.B . Jira [8])
     - 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: wir müssen es schaffen, dass viele Bereiche, die aus Sicht des Kunden stabil sind, auch stabil hinsichtlich der Dokumentation sind. 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 auch vor, wo die Grenzen sind, d. h. was gehört in ein Artefakt und – was oft noch wichtiger ist – was in einem Artefakt nicht zu beschreiben ist.

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. [9]

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.

Ich habe darum mit einer stark technischen Perspektive die Struktur der Dokumentation als UML-Klassendiagramm modelliert. Das Metamodell verschafft uns einen groben Überblick über die Struktur der Dokumentation und die Zusammenhänge zwischen den Artefakten. Die Klassen im Metamodell enthalten die Beschreibung des erwarteten Inhaltes, der Regeln für die Fertigstellung und eine Vorlage für den formalen Aufbau des Artefaktes.

Metamodell Requirements

  • Themenbereiche
  • Systemfunktionen
  • Anwendungsfälle
  • Glossar
  • Linksammlung
  • Meldungskatalog

Metamodell User Interface

  • Fenster
  • Dialoge
  • Berichte
  • Icon-Library

Metamodell User Manuals

  • Benutzerhandbuch
  • Trainingsunterlagen

Metamodell Components Model

  • Komponentenschnitt
  • Schichtenmodell
  • Fachklassen

Metamodell Instruction Manuals

  • Installationsanleitungen
  • Handlungsanweisungen
  • Betriebshandbuch

Metamodell Architecture

  • Technische Konzepte
  • Entscheidungen
  • Programmierrichtlinien
  • Programmieranleitungen

Die Erstellung und Pflege des Metamodells unterscheiden sich nach meiner Ansicht nicht wesentlich von der Erstellung und Pflege von Modellen zur Definition einer Software-Architektur. Ich meine, dass dieses Metamodell eine Art "Dokumenten-Architektur" ist, vergleichbar mit Architekturen für Standard-Software. Wir benötigen einen "Gärtner" (Gardener) für diese Lösung, jemand, der die "zarten Pflanzen" (Pages) in der "Parkanlage" (Wiki) hegt und pflegt!

Der Gardener ist immer als Coach greifbar und hilft bei der Bewältigung von alltäglichen wie auch speziellen Problemen im Zusammenhang mit Dokumentation. Ähnlich einem Software-Architekten ist der Gardener verantwortlich für

  • die Wahl der Werkzeuge (sozusagen die Entwicklungsumgebung für die Analysten),
  • die Formulierung und Durchsetzung von Dokumentationsrichtlinien (wie die Programmierrichtlinien für Entwickler),
  • die Umsetzung von Erweiterungen, wenn der Bedarf erkannt wurde, und
  • die Erreichung der geforderten Qualität der Lösung.

Ganz ehrlich: Niemand baut ein technisches System ohne sich Gedanken über den Aufbau der Software zu machen. Es wird immer jemanden geben, der Anforderungen bewertet und kommuniziert, Strukturen und Konzepte entwirft und die Umsetzung begleitet.

Ein Wiki ist ein technisches System.

Auch ein Wiki braucht diese Form der Aufmerksamkeit. Als Forum vor allem für die Erweiterung und Korrekturen des Wiki bietet sich eine sogenannte "Community of practice" an, die natürlich durch das Projekt auch das Mandat haben muss, entsprechende Entscheidung über Änderungen treffen können.

Produktionskette

Beim Entwurf unserer Lösung haben wir versucht, die Vorteile der agilen Methode mit den bewährten Ansätzen aus der klassischen Anforderungsanalyse so optimal wie möglich zu verbinden, um eine nachhaltige und vollständige Systembeschreibung zu erstellen, zu pflegen und langfristig für unseren Auftraggeber zu erhalten. Unser Ziel im Projekt ist es, den Aufwand für diese Aufgabe so gering wie möglich zu halten. Und dabei soll uns die Methode unterstützen.

Im Zusammenhang mit Wissensmanagement brauchen wir klare Strukturen, um Wissen zu erhalten. Wissen wird nicht vollständig auf einmal vermittelt, sondern wird in einem Prozess erarbeitet, der Zeit braucht. Die Strukturen stellen sicher, dass man Wissen in der Form konserviert, in der wir sie von den Wissensträgern erhalten. Die Artefakte sind so definiert, dass sie immer ein Ergebnis eines Schrittes sind und von den Wissensträgern geprüft werden. Zur Beurteilung, ob ein Artefakt fertig für den nächsten Schritt ist, verwenden wir die in agilen Methoden bereits bekannte "Definition of Ready".

Die Abfolge der Schritte bezeichnen wir als Produktionskette. Die Schritte der Produktionskette führen dazu, dass wir unser Product-Backlog ausreichend füllen mit User-Stories von hoher Qualität. Epics und User-Stories nutzen wir, um dem Team alle zusätzlichen Informationen zur Umsetzung in einem konkreten Release zu geben. Am Ende des Releases können wir Epics und User-Stories ohne Wissensverlust "entsorgen".

Ich möchte die Produktionskette als eine Art Kochrezept formulieren. Ein gutes Kochrezept enthält Angaben über die Anzahl oder Menge der benötigten Zutaten (=Artefakte) für ein Gericht (=Systembeschreibung) sowie Anweisungen über Art und Reihenfolge ihrer Verwendung und Zubereitung (=Produktionskette).

Die vorgestellte Methode – das Grundrezept – kann an unterschiedliche Bedürfnisse angepasst werden. Es funktioniert für eine einfache Anforderung mit einer Benutzeroberfläche in einem normal komplexen System. Wir haben aber auch Rezepte für aktualisierende Benutzeroberflächen, komplexe Geschäftslogik, technische Schnittstellen oder im Hintergrund ausgeführte interne Prozesse. Aber wie beim Kochen ändern wir nicht die Zutaten für das Gericht!

Zutaten für eine Anforderung

  1. Ein Topic
  2. Ein Feature
  3. Cases für die Geschäftslogik
  4. Layouts für die Benutzeroberfläche

Schritt 1: Übernahme der Anforderung in das Projekt

Der Bedarf an einer neuen Funktion im System entsteht in den Fachabteilungen. Sie wird als Anforderung erfasst und dem Projekt zur Verfügung gestellt. In Zusammenarbeit mit den Stakeholdern prüft der Product-Owner die Anforderung, ob sie fachlich in den Kontext des Systems passt. Ein wesentliches Kriterium für die Übernahme der Anforderung ist, ob sie eindeutig einem Topic zugeordnet werden kann. Das Topic hat daher einen hohen Wert, weil unklare oder zu große Anforderungen sehr früh erkannt werden. Kann eine Anforderung nicht eindeutig einem Topic zugeordnet werden, dann hat der Product-Owner die Aufgabe, die Anforderung zu teilen. Die neu entstandenen Anforderungen können dann eindeutig einem Topic zugeordnet werden. Eine Anforderung kann auch dazu führen, dass ein neues Topic erstellt wird, wenn kein existierendes Topic passt. In diesem Fall hat der Product-Owner die Aufgabe, mit den Stakeholdern zu verhandeln, ob es ein neues Topic im System gibt. Ganz wesentlich ist hier die Diskussion darüber, ob die Anforderung tatsächlich in diesem System umgesetzt wird oder ob nicht vielleicht doch ein anderes System besser geeignet wäre.

Schritt 2: Analyse der Anforderung

Sobald eine Anforderung einem Topic zugeordnet wurde, beginnt der Product-Owner mit seinem Team die Analyse der Anforderungen. Für jede Anforderung legen wir ein Feature im Wiki an. Wir formulieren die Motivation und erstellen eine grobe Skizze der Anforderung. Ein ganz wichtiges Ergebnis ist die Abgrenzung zu anderen Anforderungen, auch zu den bereits umgesetzten. Anforderungen können sich ergänzen, aber auch widersprechen. Diese Konflikte müssen vom Product-Owner mit den Stakeholdern geklärt werden. Im Zusammenhang mit der Analyse der Anforderung pflegen wir auch unser Glossar der Fachbegriffe. Wir machen uns bereits jetzt Gedanken über die Layouts und Cases, die zu diesem Feature gehören. Zu diesem Zeitpunkt reichen die Informationen aber nur aus, um den Titel festzulegen. Im Wiki ergibt sich dadurch schon ein guter Überblick über das Feature. Für jedes Feature legen wir ein gleichnamiges Epic an. Dadurch ergibt sich im Wiki und in der Vorgangsverwaltung eine gemeinsame Struktur, in der sich jeder im Team schnell zurecht findet. Das Epic ist in unserem Fall nur ein Platzhalter des Features in der Vorgangsverwaltung.

Schritt 3: Spezifikation der Anforderung

Die Spezifikation der Anforderung bewegt sich parallel auf zwei Ebenen:

  1. Die Benutzeroberfläche definieren wir mit Layouts
  2. Geschäftslogik beschreiben wir mit Cases.

Das Mockup im Layout ist das Grundgerüst für die Benutzeroberfläche in der gegebenen Architektur. Das Layout beinhaltet außerdem die Beschreibung der "Mechanik" der Benutzeroberfläche, also Initialisierung und Validierung der Steuerelemente und Verknüpfungen der Schaltflächen zu den Cases. Die Zielgruppe für Layouts sind vorrangig die Entwickler.

Beim Schreiben eines Case macht sich der Analyst immer bewusst, was ein Entwickler oder Tester fragen würde. Und er nutzt das Refinement, um Feedback von den Entwicklern und Testern zu bekommen.

Ein Case ist in sich abgeschlossen, testbar und klein genug, um in einem Sprint umgesetzt zu werden.

Ein Nutzer würde durch die Beschreibung der Ausgangssituation in die Lage versetzt, die beschriebene Situation in der Anwendung herzustellen. Die fachliche Lösung zeigt im wörtlichen Sinn nur die Essenzschritte, die in der Anwendung zum erforderlichen Ergebnis führt. Bei der Beschreibung der Lösung müssen wir ganz stark darauf achten, dass wir sie aus Sicht der Nutzer beschreiben, nicht die technische Lösung – die kennt ein Entwickler in den meisten Fällen gut genug.

Für jede Änderung an einem Layout legen wir eine gleichnamige User-Story an. Dadurch setzt sich im Wiki und in der Vorgangsverwaltung die mit dem Epic begonnene gemeinsame Struktur fort. Die Beschreibung der User-Story besteht ausschließlich aus Verlinkungen in das Wiki. Der Product-Owner und das Team kann die Akzeptanzkriterien der User-Story benutzen, um Details festzulegen, die für die Umsetzung im Sprint notwendig sind.

Schritt 4: Umsetzung der Anforderung

Im Planning stellt der Product-Owner den Sprint aus User-Stories im Product-Backlog zusammen und das Team gibt sein Commitment ab, basierend auf den Informationen, die es im Wiki findet. Mit dem Commitment des Teams sind die Inhalte der Systembeschreibung aus den User-Stories für die Dauer des Sprints für andere Teams "eingefroren".

Das direkte Feedback des cross-funktionalen Teams ist sehr wichtig für die Qualität der Systembeschreibung.

Während des Sprints entdecken Entwickler oder Tester regelmäßig neue Sonderfälle oder Fehlersituationen, die schnell fachlich geklärt und vom Analysten im Team als weiterer Case dokumentiert werden. Manche Fehler oder Lücken in den Layouts – speziell die Abschnitte Initialisierung und Validierung – erkennen wir erst während der Entwicklung. Am Ende des Sprints befinden sich alle wichtigen fachlichen Informationen in der Systembeschreibung.

Das Wissen aus diesem Sprint ist gesichert! Das cross-funktionale Team hat als Gemeinschaft nicht nur das Produkt verbessert, sondern auch die begleitende Dokumentation, indem es die Systembeschreibung als Unterlage für die Arbeit verwendet und im Sinne der Pfadfinderregel verbessert.

Fazit

Der große Vorteil dieser Produktionskette ist unter anderem auch die Tatsache, dass wir am Ende eines jeden Schrittes abbrechen können, ohne bis zu diesem Zeitpunkt gesammeltes Wissen zu verlieren. Ein weiterer Vorteil ist, dass wir immer sicher sind, am Beginn eines Schrittes die Inhalte im Wiki vorzufinden, die wir brauchen, in der Qualität, die wir fordern.
 Dieses Vorgehen fordert ein hohes Maß an Disziplin und Bereitschaft zu trainieren, um sich zu verbessern – frei nach dem Motto “Nutze deine Stärken, trainiere deine Schwächen”.
Wir müssen uns die schon lange von Entwicklern im Zusammenhang mit Programmierung verwendeten Praktiken auch für das Dokumentieren zu eigen machen. Die professionelle Erstellung und Pflege technischer Dokumentationen unterscheidet sich nach meiner persönlichen Einschätzung nur wenig bis gar nicht von professioneller Programmierung.

Autor

Robert Bruckbauer

Robert Bruckbauer ist Berater bei der eMundo GmbH in München. Er ist in der Softwareentwicklung tätig und entwickelte mit Fortran, C und C++; mittlerweile hat er viel Erfahrung in der Programmierung von Anwendungen mit Java und...
>> Weiterlesen
botMessage_toctoc_comments_9210