ObjektSpektrum 06/11

Optimale Systemdokumentation mit agilen Prinzipien

Autor:

Die Diskussion ist fast so alt wie die IT: Wie viel Dokumentation benötigt ein System? Während es für den Kunden oft nicht genug sein kann, möchte der typische Entwickler am liebsten ausschließlich Code erzeugen. Eine leicht falsch interpretierbare Aussage aus dem Agilen Manifest zum Thema Dokumentation hat die Diskussion noch weiter aufgeheizt. Guter Rat scheint teuer. Aber so schwierig ist es letztlich gar nicht und ein wenig Systematik bei den Dokumentationsarten sowie gerade die agilen Prinzipien helfen, Inhalt und Umfang einer guten Systemdokumentation zu optimieren. In diesem Artikel werden zwei einfache Werkzeuge vorgestellt, die helfen, Dokumentation nicht mehr auf „Verdacht“ zu erstellen, sondern zielgerichtet nach Sinn und Wert zu optimieren.

Zum Thema Systemdokumentation gibt es immer wieder lange und leidenschaftlich geführte Debatten. Von den Vertretern ausufernder, viele hundert und tausend Seiten langer Dokumentationen bis hin zu den radikalen „Code-only“ – Verfechtern findet man in der IT alle Abstufungen, die ihre Positionen vehement vertreten. Gerade im Verhältnis Kunde-Dienstleister scheinen die Gegensätze häufig aufeinanderzuprallen: Während der Kunde eine umfassende Dokumentation des zu liefernden Systems fordert – häufig basierend auf ausführlichen Dokumentations-Templates, die Teil des kundeneigenen Softwareentwicklungsprozesses sind -, würden viele Dienstleister am liebsten nur die Software ohne jede Dokumentation ausliefern. Schließlich ist der Code doch die einzig zuverlässige Informationsquelle, oder?

Das agile Missverständnis

Zu zusätzlichen Irritationen führte ein Wert aus dem agilen Manifest (vgl. Cun01): „… we have come to value: Working software over comprehensive documentation“, (etwa: „Funktionierende Software ist uns wichtiger als umfassende Dokumentation)“. Dieser Wert wurde sowohl von Befürwortern als auch von Gegnern der Agilität häufig dahingehend (miss)interpretiert, dass agile Software-Entwicklung nur noch lauffähige Software ausliefert und überhaupt keine Dokumentation mehr. Der relativierende Satz „That is, while there is value in the items on the right, we value the items on the left more“ (etwa: „Während wir die Dinge auf der rechten Seite durchaus als wertvoll ansehen, finden wir die Dinge auf der linken Seite wertvoller“), der den vier Werten im Manifest folgt, wurde dabei geflissentlich überlesen.

An dieser Stelle hilft vielleicht noch einmal eine kleine Klarstellung bzgl. der Motivation hinter dem Wert aus dem Manifest: Dokumentation hat auch in der Agilität ihren festen Platz und kein seriöser Befürworter von agiler Software-Entwicklung würde Dokumentation pauschal als unnötig bezeichnen. Der Wert an sich ist am besten zu verstehen, wenn man das agile Manifest im Kontext seiner Entstehungszeit betrachtet: Die späten 90er Jahre waren geprägt von großen, eher schwergewichtigen Prozessen, die häufig Unmengen an Dokumentation jedweder Art produzierten. Die eigentliche Software ist darin eher zur minder wichtigen Randerscheinung degradiert. Der Prozess und die ganzen Dokumente drohten zum Selbstzweck zu verkommen.

Davon distanzierte sich die agile Bewegung ganz klar. Sie stellte die Wertschöpfung in das Zentrum ihres Interesses, und der primäre Wert in der Software-Entwicklung ist eine lauffähige und qualitativ hochwertige Software. Konsequenterweise wurde die Software an sich wieder zurück in den Fokus gerückt und erhielt so ihren verdienten Stellenwert zurück. Dokumentation hingegen wurde nur als wichtig erachtet, wenn sie einen erkennbaren Mehrwert für das Gesamtergebnis beisteuert. Dieser Schritt war zu seiner Zeit sehr wichtig und lieferte wertvolle Impulse auch außerhalb der agilen Bewegung.

In der Agilität geht es also nicht um eine pauschale Dokumentationsvermeidung, sondern um eine wertbasierte Abwägung, die ich im weiteren Verlauf noch nutzen werde, um die benötigte Dokumentation zu optimieren.

Stakeholder, ihre Fragen und Dokumentation

Dokumentation ist wichtig

Um uns einer optimalen Systemdokumentation anzunähern, sollten wir vielleicht am besten mit der Frage beginnen, wie wichtig Dokumentation tatsächlich ist. Schauen wir uns dafür zwei Beispiele an:

  • Als Administratoren sollen wir eine große, mehrere Dutzend Personenjahre schwere Individual-Software in Betrieb nehmen. Leider gibt es keine Zeile Dokumentation dazu und es ist auch niemand zu finden, der uns etwas zu der Software sagen kann. Wir haben nur eine CD – leider ohne irgendeinen Installer – und das war’s.
  • Wir sind ein Projekt-Team, das seinen Projektstatus komplett transparent im Unternehmens-Wiki verwaltet. Anhand einer einfacher Darstellung kann man zu jedem Zeitpunkt sehen, was wie weit ist und ob der nächste Termin gefährdet ist. Außerdem arbeiten wir mit kurzen Iterationen von zwei Wochen und zeigen am Ende jeder Iteration die fertiggestellte Software auf dem Zielsystem. Trotzdem will unser Management, dass wir jede Woche einen Projektstatusbericht auf Basis einer 15-seitigen Vorlage anfertigen, damit es den Status des Projekts bewerten kann.

Mit diesen – zugegebenermaßen recht extremen – Beispielen haben wir die Bandbreite der Wichtigkeit von Dokumentation recht weit ausgelotet. Während die Dokumentation im ersten Beispiel essentiell ist (ohne sie wird der arme Administrator seine Aufgabe wohl nicht erfüllen können), ist sie im zweiten Fall eher ärgerlich und ohne erkennbaren Mehrwert.

Andererseits kann man bei einem einfachen Desktop-Utility, das mit einem fertigen Installer kommt, vielleicht komplett auf Dokumentation verzichten, während es sicherlich auch Projekte gibt, bei denen ein regelmäßiger Statusbericht die einzige Chance für das Management ist, sich einen rudimentären Einblick in den Status des Projektes zu verschaffen. Man kann die Wichtigkeit von bestimmten Dokumenten also nicht pauschal beantworten, sondern muss sie individuell bewerten.

Aber wie kommen wir zu einer individuellen Bewertung der Wichtigkeit von Dokumentation? Auf dem Weg dahin fehlen noch zwei Bausteine:

  • Die Aufgabe von Dokumentation – wofür benötigen wir überhaupt Dokumentation?
  • Arten von Dokumentation – eine minimale Systematik

Der erste Baustein hilft uns, die Werthaltigkeit eines Dokuments zu ermitteln. Wenn ich den Zweck von Dokumentation im Allgemeinen verstanden habe, kann ich bewerten, inwieweit ein bestimmtes Dokument zu diesem Zweck beiträgt. Den zweiten Baustein benötigen wir, da es je nach Dokumentationsart unterschiedliche Herangehensweisen und Handlungsmöglichkeiten gibt.

Ziele von Dokumentation

Beginnen wir mit dem ersten Baustein: Wofür benötigen wir Dokumentation überhaupt? Was ist ihre Aufgabe? Auf diese Frage gibt der IEEE-Standard 1471:2000 [IEEE] eine sehr gute Antwort. Eigentlich bezieht sich dieser Standard zwar auf die Dokumentation von Architekturen, aber der hieraus relevante Teil (siehe Abbildung 1) ist für jede Art von Dokumentation zutreffend: Stakeholder haben Fragestellungen, die für sie wichtig sind und auf die sie gerne Antworten haben möchten bzw. haben müssen. Die Aufgabe der Dokumentation ist es, diese Fragen zu beantworten. Das ist die Kernaussage.

Ergänzend empfiehlt der Standard noch, die Fragestellungen in Sichtweisen zu bündeln und die Dokumentation anhand dieser Sichtweisen zu strukturieren. Das ist eine nützliche Empfehlung, weil sie einem hilft, die Dokumentation zielgruppen- und fragestellungsgerecht zu organisieren.

Die Aufgabe der Dokumentation ist damit klar. Wie sieht es aber mit dem Umkehrschluss aus: Wenn Dokumentation die Fragen von Stakeholdern beantwortet, muss ich dann für jede mögliche Frage eines Stakeholders ein Stück Dokumentation schreiben? Nein, natürlich nicht.

Zum einen kann es in vielen Fällen hinreichend (und häufig auch effektiver) sein, Fragen direkt im Dialog zu klären anstatt dafür ein Stück Dokumentation zu schreiben. Wenn etwa der Sicherheitsbeauftragte eines Unternehmens Fragen zu der neu einzuführenden Software hat, dann ist es oftmals für beide Seiten um Längen effizienter, sich einmal zusammenzusetzen und die Fragen im Gespräch zu klären, als dafür ein großes Dokument zu schreiben, das in der Regel dann doch nicht alle Fragen klärt. Wenn dieser Weg also sinnvoll ist, dann sollte man ihn bevorzugen.

Zum anderen kann auch das Produkt selber diverse Fragen direkt beantworten. Dafür muss dann keine redundante Dokumentation geschaffen werden. So brauche ich z.B. in der Regel keine Dokumentation von Klassen und Methoden außerhalb des Quellcodes, wenn diese Information ausschließlich für die Entwickler des Systems von Interesse ist (was meistens der Fall ist). Diese Information können sich die Entwickler auch direkt aus dem Quellcode beschaffen. In Abbildung 2 ist das noch einmal bildlich zusammengefasst.

Stakeholder

Projekt- und Systemdokumentation

Kommen wir zu dem zweiten Baustein, den Arten von Dokumentation. Als minimale Systematik können wir zwei grundlegende Arten von Dokumentation im Kontext der meisten Software-Entwicklungsprojekte unterscheiden:

  • Projekt- bzw. Prozessdokumentation
  • Produkt- bzw. Systemdokumentation

Die Projekt- bzw. Prozessdokumentation umfasst Dokumente, die an das jeweilige Projekt und sein Vorgehensmodell (den Prozess) gebunden sind. Das sind die Artefakte, die die typischen Vorgehensmodelle an den Übergabepunkten zwischen verschiedenen Rollen oder Aktivitäten vorschreiben. Das sind z.B. Anforderungsspezifikationen, Konzepte und Modelle, aber auch Projektpläne, Projektstatusberichte und Meeting-Protokolle. All diesen Dokumenten ist eines gemein: Ist das Projekt beendet, sind diese Dokumente üblicherweise nicht mehr relevant.

Die Produkt- bzw. Systemdokumentation hingegen beschreibt Dokumente, die direkt zum fertigen System gehören. Das sind z.B. Installationsanleitungen, Betriebs- und Administrationshandbücher, evtl. rechtlich vorgeschriebene Zertifikate oder auch Benutzerhandbücher. Alle Dokumente sind ein integraler Bestandteil des finalen Produkts, d.h. ohne sie ist das Produkt nicht vollständig. Die lauffähige Software ist natürlich der Kern des Produkts, aber ohne die zugehörige Systemdokumentation ist die Software in der Regel nicht einsetzbar – gerade im Bereich der Individual-Softwareentwicklung.

Bei dieser Unterscheidung sind noch zwei weitere Aspekte von Interesse. Der erste Aspekt betrifft den Produktlebenszyklus: In der Regel kann man die Erstellungsphase einer Software und ihre Betriebs- und Wartungsphase unterscheiden. Das ist nicht immer ganz einfach, z. B. in agilen Projekten in denen die Software häufig schon produktiv gesetzt wird, während parallel dazu noch die initial geplante Funktionalität weiterentwickelt wird, aber auch in diesen Fällen kann man die Phasen zumindest inhaltlich unterscheiden, wenn auch nicht zeitlich. Hierzu gibt es verschiedene Untersuchungen (für eine Übersicht siehe z.B. [Kos03]). Man kann heute davon ausgehen, dass die Betriebs- und Wartungsphase bzgl. Zeit und Aufwand im Schnitt mindestens um den Faktor 5 größer ist als die Erstellungsphase (Tendenz steigend). In agilen Projekten dürfte der Faktor noch deutlich größer sein, weil diese Projekte üblicherweise sehr früh in Produktion gehen.

Die Projektdokumentation bezieht sich auf die Erstellungsphase. Das ist die Dokumentation, die man zur ordnungsgemäßen Abwicklung dieser Phase benötigt. Die Systemdokumentation benötigt man insbesondere für die Zeit nach dem Projekt, d.h. für die Betriebs- und Wartungsphase. In dieser Zeit existiert das Projektteam typischerweise nicht mehr und auch viele andere Ansprechpartner sind nicht mehr verfügbar. Die Systemdokumentation sollte daher mindestens alle Informationen umfassen, die benötigt werden, um das System auch ohne die bei der Erstellung verfügbaren Personen betreiben, nutzen und warten zu können. Nebenbei unterstreicht das Verhältnis zwischen Erstellungsphase und Betriebs-/Wartungsphase eindrucksvoll die Wichtigkeit der Systemdokumentation – und die relative Unwichtigkeit der Projektdokumentation (Siehe Abbildung 3).

Eine etwas andere Situation liegt vor, wenn das System über seinen ganzen Lebenszyklus von einem festen Team entwickelt und gewartet wird, wir es also zumindest inhaltlich (kommerziell kann das anders geregelt sein) nicht mehr mit abgeschlossenen Projekten zu tun haben, sondern einer kontinuierlichen Systementwicklung. Hier stünden prinzipiell Ansprechpartner über den gesamten Lebenszyklus zur Verfügung, womit sich die zuvor beschriebene Wichtigkeit von Systemdokumentation wieder etwas relativieren würde. Allerdings sind – insbesondere in Kunde/Dienstleister-Beziehungen – abgeschlossene Projekte der Regelfall und eine durchgängige Begleitung eines Systems durch ein festes Team über den gesamten Lebenszyklus eher die Ausnahme.

Der zweite Aspekt bezieht sich auf das Kunde/Dienstleister-Verhältnis: Hier muss man ein wenig aufpassen. Viele Kunden bestehen auf einer ganzen Menge an Dokumentation, die sie zusammen mit einem Software-System geliefert haben wollen und ohne die sie das System nicht abnehmen wollen. Hier muss man genauer hinschauen: Handelt es sich dabei wirklich immer um Systemdokumentation gemäß der zuvor beschriebenen Definition oder besteht der Kunde auf dem Dokument, weil es Teil seines Prozessmodells ist bzw. er es aus anderen projekttechnischen Gründen haben will?

Das muss man genauer hinterfragen, weil es häufig nicht differenziert wird. Nicht jedes vom Prozessmodell vorgeschriebene Artefakt ist automatisch Projektdokumentation, sondern kann sehr wohl ein Systemdokument beschreiben. Nicht jedes vom Prozessmodell abnahmerelevante Dokument ist automatisch Teil der Projektdokumentation, sondern kann sehr wohl ein Systemdokument beschreiben. Aber nicht jedes gemäß Prozessmodell abnahmerelevante Dokument ist automatisch Teil der Systemdokumentation. Für diese Unterscheidung sollte man die zuvor beschriebenen Definitionen heranziehen und jedes der geforderten Dokumente diesbezüglich hinterfragen. Dieses Hinterfragen kann einem bei der Bestimmung der optimalen Systemdokumentation sehr hilfreich sein, wie gleich zu sehen ist.

Relevanz der Dokumentation

Optimale Systemdokumentation

Damit haben wir alle Informationen, die wir benötigen, um uns Gedanken über eine optimale Systemdokumentation zu machen: Wir kennen die Aufgabe von Dokumentation und können Projekt- und Systemdokumentation voneinander unterscheiden.

Für die Bewertung der Dokumentation ziehen wir den agilen Mehrwertgedanken heran: Wir prüfen den Wertbeitrag der Dokumentation bezogen auf ihre Aufgabenstellung und ihren Kontext (Projekt- oder Systemdokumentation) und vermeiden Dokumentation mit geringem Wert. Das Prinzip lautet also nicht, was möglich ist, sondern was nötig ist.

Dafür möchte ich zwei einfache, aber bewährte Vorgehensweisen anbieten:

  • Vermeidung von Projekt- bzw. Prozessdokumentation
  • Produkt- bzw. Systemdokumentation – Stakeholder-basierte Analyse

Beginnen wir mit der Projektdokumentation: Projektdokumentation ist keine Systemdokumentation. So gesehen gehört dieser Teil streng genommen gar nicht in den Artikel. Da hier aber erfahrungsgemäß eine Menge Optimierungspotential besteht, möchte ich hier trotzdem darauf eingehen.

Dokumentationsvermeidung

Im Projektkontext ist es wichtig, die Fragestellungen der verschiedenen beteiligten Stakeholder aktiv zu managen. Welche Fragen und Sorgen haben sie, was brauchen sie, damit sie diese Sorgen nicht mehr haben? Sofern es sinnvoll möglich ist, sollte man immer versuchen, hierfür die direkte Kommunikation und keine Dokumentation zu nutzen. Erstens ist das fast immer mit weniger Aufwand für alle beteiligten Parteien verbunden, zweitens ist es fast immer schneller und zum dritten ist direkte Kommunikation deutlich weniger fehleranfällig (im Sinne von Missverständnissen und Fehlinterpretationen) als ein Dokument.

Nur wenn der Weg der direkten Kommunikation nicht möglich ist, sollte Dokumentation eingesetzt werden. Wann ist direkte Kommunikation nicht möglich? Dafür kann es verschiedene Gründe geben. Häufige Gründe dafür sind:

  • Großes Projekt: Je größer das Projekt ist, desto mehr formale Kommunikationsstrukturen benötigt man, da die direkte Kommunikation nicht gut skaliert. Das beinhaltet dann auch einen verstärkten Einsatz von schriftlicher Kommunikation, insbesondere auch Dokumentation.Verteiltes Projekt: In einem über mehrere Standorte verteilten Projekt ist direkte Kommunikation häufig nur sehr schwer möglich. Auch hier steigt die Notwendigkeit, mehr Dokumentation zur Kommunikation zu nutzen.
  • Hohes Risiko: Ein riskantes Projekt erfordert Maßnahmen, um das Risiko beherrschbar zu halten. Dies erfordert in der Regel auch mehr Dokumentation von Beschlüssen und Aktivitäten, um die Transparenz und Nachvollziehbarkeit sicherzustellen.
  • Gesetzliche Anforderungen: In verschiedensten Umfeldern gibt es gesetzliche Anforderungen, die die Dokumentation von Projektaktivitäten und Beschlüssen erforderlich machen, auch wenn sie ansonsten keinen weiteren Wertbeitrag liefern als die gesetzlichen Vorgaben zu erfüllen.

Aber auch wenn wir wahrscheinlich in der Regel nicht schaffen werden, komplett ohne Projektdokumentation auszukommen, so sollten wir doch immer den Wertbeitrag kritisch hinterfragen und prüfen, ob es nicht auch ohne das jeweilige Dokument geht oder zumindest mit einem reduzierten Dokument. Hier ein paar Beispiele:

  • Brauchen wir wirklich eine detaillierte Spezifikation? Reichen nicht auch User Stories und eine „Just-in-Time“-Abstimmung zwischen Entwickler und Fachanwender?
  • Brauchen wir wirklich regelmäßig den erwähnten 15-seitigen Statusreport? Reicht nicht auch eine wöchentliche Telefonkonferenz?
  • Und würde eine Vorführung lauffähiger Software alle 2, 3 oder 4 Wochen nicht wesentlich mehr Aussagekraft haben (und für mehr Vertrauen bei den Projektsponsoren sorgen) als jeder noch so detaillierte Statusreport?

Ergänzend hilft es, regelmäßig zu prüfen, ob ein Dokument noch werthaltig ist. So kann eine Architekturskizze zu Beginn des Projekts sehr wertvoll gewesen sein, mittlerweile aber überholt sein. Anstatt die Skizze nachzupflegen, ist es häufig sinnvoller, sie als „veraltet“ zu kennzeichnen und in ein Archiv zu verschieben.

Mit diesen Empfehlungen sollte es möglich sein, ein gutes Maß an Projektdokumentation festzulegen. Hier ist bei traditionellen Vorgehensmodellen häufig das größte Einsparpotential und genau dieses ist auch primär im agilen Manifest adressiert worden. Das geht nicht von alleine und Sie werden je nach Umgebung sicherlich eine Menge Überzeugungskraft aufbringen müssen, um liebgewonnene, aber eigentlich wertlose Projektdokumente loszuwerden, aber den Aufwand ist es aus meiner Erfahrung wert.

Soviel als Empfehlung zur Behandlung von Projektdokumentation. Wie sieht es mit der Produkt- bzw. Systemdokumentation aus? Wie viel benötigen wir da?

Systemdokumentation: Stakeholder-basierte Analyse

Ganz so einfach geht es für die Systemdokumentation nicht, weil wir ja insbesondere die Zeit nach dem Projekt betrachten müssen. Wie finden wir dafür einen optimalen Dokumentationsumfang, der auf der einen Seite alle relevanten Informationen enthält, auf der anderen Seite aber so gering wie möglich ist?

Meine Empfehlung dafür ist eine Stakeholder-basierte Analyse. Diese orientiert sich ebenfalls am agilen Mehrwertprinzip, indem sie systematisch den tatsächlichen Informationsbedarf erfasst und damit das minimal notwendige Dokumentationsset zu einem System definiert. Die Stakeholder-basierte Analyse orientiert sich an dem zuvor beschriebenen IEEE-Standard und funktioniert folgendermaßen:

1. Identifiziere alle für die Inbetriebsetzung sowie für Betrieb und Wartung relevanten Stakeholder. Ich betrachte die Inbetriebsetzung ebenfalls, weil es häufig Dokumente gibt, die notwendig sind, damit das System eine Betriebsfreigabe erhält (z.B. im Sicherheits- oder Datenschutzumfeld).

2. Identifiziere die Fragestellungen dieser Stakeholder. Es sollte dabei nicht jede Einzelfrage erfasst werden, sondern die Themenfelder. Als Faustregel tut es in der Regel eine einstellige Zahl Fragestellungen pro Stakeholder.

3. Leite aus den Fragestellungen Themengebiete für die Dokumentation ab.

4. Bündle die Themengebiete nach Inhalten und Zielgruppen in Dokumenten (Stichwort: Sichtweisen).

5. Halte die Inhalte der Dokumente als Verzeichnisstruktur mit kurzen Erläuterungen je Kapitel fest („In diesem Kapitel steht …“).

6. Gib die Dokumente mit den Verzeichnisstrukturen und Inhalten den Stakeholdern zum Review.

Wichtig ist hierbei, dass das keine Veranstaltung im stillen Kämmerlein ist, sondern sehr interaktiv erfolgt. Sprechen Sie mit möglichst vielen Parteien, um die relevanten Stakeholder zu ermitteln. Es ist erstaunlich, wie häufig der Fachbereich oder die IT-Entwicklung Ihres Auftraggebers nicht wissen, wer alles in Betrieb und Wartung des beauftragten Systems involviert ist. Nicht selten werden Sie regelrechte Aha-Erlebnisse bei Ihren Auftraggebern auslösen, wenn Sie die Stakeholder einmal transparent machen.

Und raten Sie nicht, welche Fragen die Stakeholder haben könnten. Sprechen Sie mit ihnen! Zum einen werden Sie häufig feststellen, dass die Fragestellungen andere sind, als Sie angenommen haben. Zum anderen lässt sich so häufig eine Differenzierung zwischen wirklich wichtigen Informationen und „Nice to have“-Informationen herausarbeiten und so viel Aufwand einsparen. Zum dritten kann man so manche Frage auch direkt bei der Abstimmung beantworten und muss dafür dann gar nichts schreiben – wiederum gesparter Aufwand. Wichtig ist auch, die erarbeiteten Dokumenten-Templates den Stakeholdern zum Review zu geben, um frühzeitig Feedback zu erhalten und so unangenehme Überraschungen kurz vor der Inbetriebsetzung zu vermeiden.

Sieht das nach viel Aufwand für ein solches Thema aus? Aus meiner Erfahrung nein. Natürlich bekommt man die notwendigen Informationen in der Regel nicht auf einem Silbertablett serviert, sondern man muss einen gewissen Klärungs- und Abstimmungsaufwand betreiben, wenn man ein gemeinsames Verständnis herstellen will. Das ist das Gleiche wie mit den Anforderungen und allen anderen Informationen. Aber aus meiner Erfahrung ist der Aufwand trotzdem recht überschaubar: einige Gespräche, Entwurf von ein paar Dokumenten-Templates und noch ein paar Abstimmungen. Das lässt sich in der Regel recht zügig erledigen.

Der Nutzen hingegen ist ungemein höher: Zum einen haben Sie Transparenz und ein gemeinsames Verständnis bzgl. der benötigten Systemdokumentation hergestellt, an einer Stelle, die häufig nur von Annahmen und Halbwissen geprägt ist. Und das führt auch schon zum zweiten Punkt: Durch das Eliminieren der Unsicherheit bzgl. der benötigten Informationen können Sie häufig den Umfang der geforderten Dokumentation stark reduzieren, weil häufig keiner so genau weiß, welche Informationen benötigt werden und deshalb sicherheitshalber alles dokumentieren lässt. Stattdessen dokumentieren Sie jetzt nur noch die wirklich benötigten Aspekte, also die Aspekte, die einen echten Mehrwert für Betrieb und Wartung liefern. Allein die hier möglichen Einsparungen rechtfertigen den Aufwand für die initiale Analyse.

Auch wenn Ihr Auftraggeber Ihnen schon (meist recht umfangreiche) Templates für die Systemdokumentation auf Basis seines Prozessmodells vorgibt, lohnt sich die Analyse häufig. So hatte ich die Analyse in einem Projekt durchgeführt und es ergab sich daraus ein Bild, das dem Beispiel in Abbildung 4 recht ähnlich war. Die Fragen einiger Stakeholder konnten direkt geklärt werden, so z.B. die der Systemplanung und des Sicherheitsbeauftragten. Andere hatten gar nicht so hohe Dokumentationsanforderungen wie initial angenommen. Auf Basis der Analyse konnte die gemäß Prozessmodell eigentlich erforderliche Dokumentation deutlich reduziert werden und aufgrund der geschaffenen Transparenz war das auch für alle Beteiligten nachvollziehbar. Der Zeitaufwand für die Analyse war im Verhältnis vernachlässigbar.

Stakeholder-basierte Analyse

Zusammenfassung

Damit haben Sie zwei einfache, agile Werkzeuge an der Hand, um eine für Sie und Ihr Projekt optimale Systemdokumentation zu schaffen, nämlich Dokumentationsvermeidung für die Projektdokumentation und Stakeholder-basierte Analyse für die Systemdokumentation. Man kann jetzt bemängeln, dass das in Summe nicht sonderlich spektakulär ist, sondern nur etwas, was man eigentlich sowieso machen sollte, ausgerichtet an ein wenig agilem Gedankengut. Dennoch habe ich immer wieder überrascht feststellen müssen, wie selten es so in der Praxis gemacht wird. Deshalb kann ich Sie nur dazu ermutigen, es in Ihrem nächsten Projekt zu versuchen und Ihre Erfahrungen damit zu sammeln.

Wie in fast allen Fällen gibt es auch für gute Systemdokumentation kein Patentrezept, keine „Silver Bullet“, weshalb ich Ihnen hier auch kein fertiges Dokumentationsset anbieten konnte. Es kommt immer auf Ihren genauen Projektkontext an, aber allein durch diese einfachen Werkzeuge haben Sie die Möglichkeit, wesentlich näher an Ihre optimale Systemdokumentation heranzukommen.

Literatur und Links

[Cun01] W. Cunnigham et. al., 2001, Manifesto for Agile Software Development, siehe: http://www.agilemanifesto.org/

[IEEE] IEEE Std. 1471-2000, IEEE Recommended Practice for Architectural Description of Software-Intensive Systems, ISBN 0-7381-2518-0

[Kos03] Koskinen, J. 2003. Software Maintenance Cost, siehe http://www.cs.jyu.fi/~koskinen/smcosts.htm

Vollständiger Artikel