WAS MUSS, WAS KANN

UND WAS GEHT GAR NICHT?

OPTIMALE SYSTEMDOKUMEN-

TATION MIT AGILEN PRINZIPIEN

wertvolle Impulse auch außerhalb der agilenBewegung. In der Agilität geht es also nichtum eine pauschale Dokumen ta -tionsvermeidung, sondern um eine wertba-sierte Abwägung, die ich im weiterenVerlauf dieses Artikels noch nutzen werde,um die benötigte Dokumentation zu opti-mieren.

Dokumentation ist wichtigUm uns einer optimalen Systemdoku -mentation anzunähern, sollten wir viel-leicht am besten mit der Frage beginnen,wie wichtig Dokumentation tatsächlich ist.Schauen wir uns dafür zwei Beispiele an:

■ Als Administratoren sollen wir einegroße, mehrere Dutzend Personenjahreschwere Individualsoftware in Betriebnehmen. Leider gibt es keine ZeileDokumentation dazu und es ist auchniemand zu finden, der uns etwas zuder Software sagen kann. Wir habennur eine CD – leider ohne irgendeinenInstaller – und das war's.

■ Wir sind ein Projektteam, das seinenProjektstatus komplett transparent imUnternehmens-Wiki verwaltet. Anhandeiner einfachen Darstellung kann manzu jedem Zeitpunkt sehen, was wie weitist und ob der nächste Termin gefährdetist. Außerdem arbeiten wir mit kurzenIterationen von zwei Wochen und zei-gen am Ende jeder Iteration die fertiggestellte Software auf dem Zielsystem.Trotzdem will unser Management, dasswir jede Woche einen Projekt-Status -

Die Diskussion ist fast so alt wie die IT: Wie viel Dokumentation benötigt ein System? Währendes für den Kunden oft nicht genug sein kann, möchte der typische Entwickler am liebsten aus-schließlich Code erzeugen. Eine leicht falsch interpretierbare Aussage aus dem Agilen Manifestzum 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 denDokumentationsarten sowie gerade die agilen Prinzipien helfen, Inhalt und Umfang einer gutenSystemdokumentation zu optimieren. In diesem Artikel werden zwei einfache Werkzeuge vor-gestellt, die helfen, Dokumentation nicht mehr „auf Verdacht” zu erstellen, sondern zielgerichtetnach Sinn und Wert zu optimieren.

m e h r z u m t h e m a :http://blog.codecentric.de/

22 23

wir die Dinge auf der rechten Seite durch-aus als wertvoll ansehen, finden wir dieDinge auf der linken Seite wertvoller”), derden vier Werten im Manifest folgt, wirddabei meist geflissentlich überlesen.

An dieser Stelle hilft vielleicht noch ein-mal eine kleine Klarstellung zu derMotivation hinter dem Wert aus demManifest: Dokumentation hat auch in derAgilität ihren festen Platz und kein seriöserBefürworter von agiler Softwareent wick -lung würde Dokumentation pauschal alsunnötig bezeichnen. Der Wert an sich istam besten zu verstehen, wenn man dasAgile Manifest im Kontext seiner Ent -stehungszeit betrachtet: Die späten 90erJahre waren geprägt von großen, eherschwergewichtigen Prozessen, die häufigUnmengen an Dokumentation jedwederArt produzierten. Die eigentliche Softwarewurde darin zur minder wichtigen Rand -erscheinung degradiert. Der Prozess unddie ganzen Dokumente drohten zumSelbstzweck zu verkommen.

Davon distanzierte sich die agile Bewe -gung ganz klar. Sie stellte die Wert schöpfungin das Zentrum ihres Interesses – und derprimäre Wert in der Soft wareentwicklung isteine lauffähige und qualitativ hochwertigeSoftware. Konse quen terweise wurde dieSoftware an sich wieder zurück in den Fokusgerückt und erhielt so ihren verdientenStellenwert zurück. Dokumentation hinge-gen wurde nur als wichtig erachtet, wenn sieeinen erkennbaren Mehrwert für dasGesamt ergebnis beisteuert. Dieser Schrittwar zu seiner Zeit sehr wichtig und lieferte

Zum Thema Systemdokumentation gibt esimmer wieder lange und leidenschaftlichgeführte Debatten. Von den Vertretern aus-ufernder, viele hundert und tausend Seitenlanger Dokumentationen bis hin zu denradikalen „Code-only”-Verfechtern findetman in der IT alle Abstufungen, die ihrePositionen vehement vertreten. Gerade imVerhältnis Kunde-Dienstleister scheinen dieGegensätze häufig aufeinanderzuprallen:Während der Kunde eine umfassendeDokumentation des zu liefernden Systemsfordert – häufig basierend auf ausführ-lichen Dokumentations-Templates, die Teildes kundeneigenen Softwareentwicklungs -prozesses sind –, würden viele Dienstleisteram liebsten nur die Software ohne jedeDokumentation ausliefern. Schließlich istder Code doch die einzig zuverlässigeInformationsquelle, oder?

Das agile MissverständnisZu zusätzlichen Irritationen führte ein Wertaus dem agilen Manifest (vgl. [Cun01]):„[...] we have come to value: Working soft-ware over comprehensive documentation”(etwa: „Funktionierende Software ist unswichtiger als umfassende Dokumenta -tion”). Dieser Wert wurde sowohl vonBefürwortern als auch von Gegnern derAgilität häufig dahingehend (miss)interpre-tiert, dass die agile Softwareentwicklungnur noch lauffähige Software ausliefert undüberhaupt keine Dokumentation mehr. Derrelativierende Satz, „That is, while there isvalue in the items on the right, we value theitems on the left more” (etwa: „Während

schwerpunk t

Uwe Friedrichsen

(E-Mail: uwe.friedrichsen@codecentric.de)

hat langjährige Erfahrungen als Architekt,

Projektleiter und Berater. Aktuell ist er bei der

codecentric AG für die strategische Entwicklung

neuer Paradigmen und Technologien verantwort-

lich und beschäftigt sich in diesem Kontext ins -

besondere mit agilen Verfahren und neuen

Architekturansätzen.

der au tor

SONDERDRUCK FÜR

3/2011

bericht auf Basis einer 15-seitigenVorlage anfertigen, damit es den Statusdes Projekts bewerten kann.

Mit diesen – zugegebenermaßen rechtextremen – Beispielen haben wir die Band -breite der Wichtigkeit von Dokumentationrecht weit ausgelotet. Während dieDokumentation im ersten Beispiel essen-ziell ist (ohne sie wird der armeAdministrator seine Aufgabe wohl nichterfüllen können), ist sie im zweiten Falleher ärgerlich und ohne erkennbarenMehrwert.

Andererseits kann man bei einem einfa-chen Dienstprogramm, das mit einem ferti-gen Installer kommt, vielleicht komplettauf Dokumentation verzichten, während essicherlich auch Projekte gibt, bei denen einregelmäßiger Statusbericht die einzigeChance für das Management ist, sich einenrudimentären Einblick in den Status desProjekts zu verschaffen. Die Wichtigkeitvon bestimmten Dokumenten kann manalso nicht pauschal beantworten, sondernmuss sie individuell bewerten. Aber wiekommen wir zu einer individuellen Bewer -tung der Wichtigkeit von Dokumentation?Auf dem Weg dahin fehlen noch zweiBausteine:

■ Die Aufgabe von Dokumentation:Wofür benötigen wir überhaupt Doku -mentation?

■ Die Arten von Dokumentation: Wiesieht eine minimale Systematik aus?

Der erste Baustein hilft uns, dieWerthaltigkeit eines Dokuments zu ermit-teln. Wenn ich den Zweck von Doku -mentation im Allgemeinen verstandenhabe, kann ich bewerten, inwieweit einbestimmtes Dokument zu diesem Zweckbeiträgt. Den zweiten Baustein benötigenwir, da es je nach Dokumentationsart un -terschiedliche Herangehensweisen undHandlungsmöglichkeiten gibt.

Ziele von DokumentationBeginnen wir mit dem ersten Baustein:Wofür benötigen wir Dokumentation über-haupt? Was ist ihre Aufgabe? Auf dieseFrage gibt der IEEE-Standard 1471–2000(vgl. [IEEE]) eine sehr gute Antwort.Eigentlich bezieht sich dieser Standardzwar auf die Dokumentation vonArchitekturen, aber der hieraus relevanteTeil (siehe Abbildung 1) ist für jede Art von

Dokumentation zutreffend: Stakeholderhaben Fragestellungen, die für sie wichtigsind und auf die sie gerne Antworten habenmöchten bzw. haben müssen. Die Aufgabeder Dokumentation ist es, diese Fragen zubeantworten. Das ist die Kernaussage.

Ergänzend empfiehlt der Standard noch,die Fragestellungen in Sichtweisen zu bün-deln und die Dokumentation anhand dieserSichtweisen zu strukturieren. Das ist einenützliche Empfehlung, weil sie hilft, dieDokumentation zielgruppen- und fragestel-lungsgerecht zu organisieren.

Die Aufgabe der Dokumentation istdamit klar. Wie sieht es aber mit demUmkehrschluss aus: Wenn Dokumentationdie Fragen von Stakeholdern beantwortet,muss ich dann für jede mögliche Frageeines Stakeholders ein Stück Dokumen -tation schreiben? Nein, natürlich nicht.

Zum einen kann es in vielen Fällen hin-reichend (und häufig auch effektiver) sein,Fragen direkt im Dialog zu klären, anstattdafür ein Stück Dokumentation zu schrei-ben. Wenn etwa der Sicherheitsbeauftragteeines Unternehmens Fragen zu der neu ein-zuführenden Software hat, dann ist es häu-fig für beide Seiten wesentlich effizienter,sich einmal zusammenzusetzen und dieFragen im Gespräch zu klären, als dafür eingroßes Dokument zu schreiben, das in derRegel dann doch nicht alle Fragen klärt.Wenn dieser Weg also sinnvoll ist, dannsollte man ihn bevorzugen.

Zum anderen kann auch das Produktselbst diverse Fragen direkt beantworten.Dafür muss dann keine redundante Doku -mentation geschaffen werden. So braucheich z. B. in der Regel keine Dokumentation

von Klassen und Methoden außerhalb desQuellcodes, wenn diese Information aus-schließlich für die Entwickler des Systemsvon Interesse ist, was meistens der Fall ist.Diese Informationen können sich dieEntwickler auch direkt aus dem Quellcodebeschaffen. In Abbildung 2 ist das nocheinmal bildlich zusammengefasst.

Projekt- und System -dokumentationKommen wir zu dem zweiten Baustein: denArten von Dokumentation. Als minimaleSystematik können wir zwei grundlegendeArten von Dokumentation im Kontext dermeisten Softwareentwicklungsprojekteunterscheiden:

■ Projekt- bzw. Prozessdokumentation■ Produkt- bzw. Systemdokumentation

Die Projekt- bzw. Prozessdokumentationumfasst Dokumente, die an das jeweiligeProjekt und sein Vorgehensmodell (denProzess) gebunden sind. Das sind dieArtefakte, die die typischen Vorgehens -modelle an den Übergabepunkten zwischenverschiedenen Rollen oder Aktivitäten vor-schreiben: beispielsweise Anforderungsspe -zifikationen, Konzepte und Modelle, aberauch Projektpläne, Projektstatusberichteund Meeting-Protokolle. All diesen Doku -menten ist eines gemeinsam: Ist das Projektbeendet, sind sie üblicherweise nicht mehrrelevant.

Die Produkt- bzw. Systemdokumentationhingegen beschreibt Dokumente, die direktzum fertigen System gehören. Das sind z. B.

schwerpunk t

Abb. 1: Der Zusammenhang zwischen Stakeholdern, ihren Fragen undDokumentation (nach [IEEE]).

bar. Die Systemdokumentation sollte dahermindestens alle Informationen umfassen,die benötigt werden, um das System auchohne die bei der Erstellung verfügbarenPersonen betreiben, nutzen und warten zukönnen. Nebenbei unterstreicht dasVerhältnis zwischen Erstellungsphase sowieBetriebs- und Wartungsphase eindrucksvolldie Wichtigkeit der Systemdokumentation– und die relative Unwichtigkeit derProjektdokumentation (siehe Abbildung 3).Eine etwas andere Situation liegt vor, wenndas System über seinen ganzen Lebens -zyklus von einem festen Team entwickeltund gewartet wird, wir es also zumindestinhaltlich (kommerziell kann das andersgeregelt sein) nicht mehr mit abgeschlosse-nen Projekten zu tun haben, sondern einerkontinuierlichen Systementwicklung. Hierstünden prinzipiell Ansprechpartner überden gesamten Lebenszyklus zur Verfügung,womit sich die zuvor beschriebene Wich -tigkeit von Systemdokumentation wiederetwas relativieren würde. Allerdings sind –insbesondere in Kunde/Dienstleister-Bezieh ungen – abgeschlossene Projekte derRegelfall und eine durchgängige Begleitungeines Systems durch ein festes Team überden gesamten Lebenszyklus ist eher dieAusnahme.

Der zweite Aspekt bezieht sich auf dasVerhältnis Kunde-Dienstleister: Viele Kun -den bestehen auf einer ganzen Menge anDokumentation, die sie zusammen miteinem Softwaresystem geliefert haben wol-len und ohne die sie das System nicht abneh-men. Hier muss man genauer hinschauen:Handelt es sich dabei wirklich immer umSystemdokumentation gemäß der obigenDefinition oder besteht der Kunde auf dem

24 25

bezüglich Zeit und Aufwand im Schnitt min-destens um den Faktor 5 größer ist als dieErstel lungsphase (Tendenz steigend). In agi-len Projekten dürfte der Faktor noch deut-lich größer sein, weil diese Projekte übli-cherweise sehr früh in Produktion gehen.

Die Projektdokumentation bezieht sichauf die Erstellungsphase. Das ist dieDokumentation, die man zur ordnungsge-mäßen Abwicklung dieser Phase benötigt.Die Systemdokumentation benötigt maninsbesondere für die Zeit nach dem Projekt,d. h. für die Betriebs- und Wartungsphase.In dieser Zeit existiert das Projektteam inder Regel nicht mehr und auch viele andereAnsprechpartner sind nicht mehr verfüg-

Installationsanleitungen, Betriebs- und Ad -ministrationshandbücher, eventuell recht - lich vorgeschriebene Zertifikate oder auchBenutzerhandbücher. Alle Doku mente sindintegraler Bestandteil des finalen Produkts,d. h. ohne sie ist das Produkt nicht voll-ständig. Die lauffähige Software ist natür-lich der Kern des Produkts, aber ohne diezugehörige Systemdokumentation ist dieSoftware in der Regel nicht einsetzbar –gerade im Bereich der Individual-Softwareent wicklung.

Bei dieser Unterscheidung sind noch zweiweitere Aspekte von Interesse. Der ersteAspekt betrifft den Produkt-Lebenszyklus:In der Regel kann man die Erstellungsphaseeiner Software und ihre Betriebs- undWartungsphase unterscheiden. Das ist nichtimmer ganz einfach, z. B. in agilenProjekten, in denen die Software häufigschon produktiv gesetzt wird, währendparallel dazu noch die initial geplanteFunktionalität weiterentwickelt wird. Aberauch in diesen Fällen kann man die beidenPhasen zumindest inhaltlich unterscheiden,wenn auch nicht zeitlich. Das eigentlicheProjekt, in dem eine Software entwickeltwird (Erstellungsphase), ist üblicherweisebezüglich Zeit und Aufwand im Verhältniszur Betriebs- und Wartungsphase sehrklein.

Hierzu gibt es verschiedene Un tersu -chungen (eine Übersicht findet sich z. B. in[Kos03]). Man kann heute davon ausgehen,dass die Betriebs- und Wartungs phase

schwerpunk t

Abb. 2: Verschiedene Quellen zur Beantwortung von Stakeholder-Fragen.

Abb. 3: Relevanz der Projekt- und Systemdokumentation im Lebenszyklus einesSystems.

3/2011

Dokument, weil es Teil seines Prozess modells ist bzw. er es ausanderen projekttechnischen Gründen haben will?

Das muss man genauer hinterfragen, weil es häufig nicht diffe-renziert wird. Nicht jeder vom Prozessmodell vorgeschriebeneArtefakt ist automatisch Projektdokumen tation, sondern kannsehr wohl ein Systemdokument beschreiben. Und nicht jedesgemäß Prozessmodell abnahmerelevante Dokument ist automa-tisch Teil der Systemdokumentation. Für diese Unter scheidungsollte man die zuvor beschriebenen Definitionen heranziehen undjedes der geforderten Dokumente daraufhin hinterfragen. DiesesHinterfragen kann bei der Bestimmung der optimalen System -dokumentation sehr hilfreich sein, wie wir gleich sehen werden.

Optimale SystemdokumentationDamit haben wir alle Informationen, die wir benötigen, um unsGedanken über eine optimale Systemdokumentation zu machen:Wir kennen die Aufgabe von Dokumentation und könnenProjekt- und Systemdokumentation voneinander unterscheiden.

Für die Bewertung der Dokumentation ziehen wir den agilenMehrwert-Gedanken heran: Wir prüfen den Wertbeitrag derDokumentation, bezogen auf ihre Auf gabenstellung und ihrenKontext (Projekt- oder Systemdokumentation), und vermeidenDokumentation mit geringem Wert. Das Prinzip lautet alsonicht, was möglich ist, sondern was nötig ist. Dafür möchte ichzwei einfache, aber bewährte Vorgehens weisen anbieten:

■ Vermeidung von Projekt- bzw. Pro zessdokumentation■ Produkt- bzw. Systemdokumentation – stakeholder-basierte

Analyse

Beginnen wir mit der Projektdokumen tation: Diese ist keineSystemdokumen tation. Streng genommen gehört dieser Teildaher gar nicht in diesen Artikel. Da hier aber erfahrungsgemäßeine Menge Opti mierungspotenzial vorhanden ist, möchte ichtrotzdem darauf eingehen.

DokumentationsvermeidungIm Projektkontext ist es wichtig, die Fragestellungen der ver-schiedenen beteiligten Stakeholder aktiv zu managen. WelcheFragen und Sorgen haben sie und was brauchen sie, damit siediese Sorgen nicht mehr haben? Sofern es sinnvoll möglich ist,sollte man immer versuchen, hierfür die direkte Kommunikationund keine Doku mentation zu nutzen. Erstens ist das fast immermit weniger Aufwand für alle beteiligten Parteien verbunden,zweitens ist es fast immer schneller und drittens ist eine direkteKommunikation deutlich weniger fehleranfällig (im Sinne vonMissver ständnissen und Fehlinterpretationen) als ein Dokument.

Nur wenn der Weg der direkten Kom munikation nicht mög-lich ist, sollte Dokumentation eingesetzt werden. Dafür, dasseine direkte Kommunikation nicht möglich ist, kann es ver-schiedene Gründe geben:

■ Großes Projekt: Je größer das Projekt ist, desto mehr forma-le Kommuni ka tionsstrukturen benötigt man, da die direkteKommunikation nicht gut skaliert. Das umfasst dann aucheinen verstärkten Einsatz von schriftlicher Kommunikation,insbesondere auch Dokumentation.

■ Verteiltes Projekt: In einem über mehrere Standorte verteil-ten Projekt ist direkte Kommunikation häufig nur sehr

schwerpunk t

schwer möglich. Auch hier steigt die Notwendigkeit, mehrDoku men tation zur Kommunikation zu nutzen.

■ Hohes Risiko: Ein riskantes Projekt erfordert Maßnahmen, umdas Risiko beherrschbar zu halten. Das erfordert in der Regelauch mehr Dokumentation von Beschlüssen und Aktivitäten,um Transparenz und Nachvollziehbarkeit sicherzustellen.

■ Gesetzliche Anforderungen: In verschiedenen Umfeldern gibt esgesetzliche Anforderungen, die die Doku mentation vonProjektaktivitäten und Beschlüssen erforderlich machen, auchwenn sie ansonsten keinen weiteren Wertbeitrag liefern, als diegesetzlichen Vorgaben zu erfüllen (vgl. Beitrag von Engler et. al.in dieser Ausgabe von OBJEKTspektrum auf Seite 44).

Aber auch, wenn wir es wahrscheinlich in der Regel nicht schaf-fen werden, komplett ohne Projektdokumentation auszukom-men, sollten wir doch immer den Wertbeitrag kritisch hinterfra-gen und prüfen, ob es nicht auch ohne das jeweilige Dokumentgeht oder zumindest mit einem reduzierten Dokument. Hier einpaar Beispiele:

■ Brauchen wir eine detaillierte Spezifi kation? Reichen nichtauch User-Storys und eine Just-in-Time-Abstim mung zwi-schen Entwickler und Fachan wender aus?

■ Benötigen wir regelmäßig den erwähnten 15-seitigenStatusreport? Reicht nicht auch eine wöchentliche Telefon -konferenz aus?

■ Hätte eine Vorführung lauffähiger Software alle zwei, dreioder vier Wochen nicht wesentlich mehr Aus sagekraft (undwürde 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 nochwerthaltig ist. So kann eine Architekturskizze zu Beginn desProjekts sehr wertvoll gewesen, 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 Projekt dokumentation festzulegen. Hier besteht bei traditio-nellen Vorgehensmodellen häufig das größte Einsparpotenzial –und genau das wurde auch primär im agilen Manifest adressiert.Das geht nicht von allein und Sie werden – je nach Umgebung –sicherlich eine Menge Überzeugungskraft aufbringen müssen,um lieb gewonnene, aber eigentlich wertlose Projektdokumenteloszuwerden, aber den Aufwand ist es aus meiner Erfahrungwert. Außerdem ist überflüssige Dokumentation sehr teuer: Siekostet (häufig viel) Geld, ohne einen Nutzen zu bringen. Deshalbist allein schon aus wirtschaftlichen Gründen ein „imZweifelsfall gegen die Dokumentation” angebracht.

Soviel als Empfehlung zur Behandlung von Projekt doku -mentation. Wie sieht es mit der Produkt- bzw. Systemdoku -mentation aus? Wie viel benötigen wir da?

Stakeholder-basierte AnalyseGanz so einfach geht es für die System dokumentation nicht, weilwir ja insbesondere die Zeit nach dem Projekt betrachten müs-sen. Wie finden wir dafür einen optimalen Dokumentations -umfang, der auf der einen Seite alle relevanten Informationenenthält, auf der anderen Seite aber vom Umfang her so geringwie möglich ist?

mit ihnen! Zum einen werden Sie häufigfeststellen, dass die Fragestellungen anderesind, als Sie angenommen haben. Zumanderen lässt sich so häufig eine Dif -ferenzierung zwischen wirklich wichtigenInformationen und „Nice to have”-Informationen herausarbeiten und damitviel Aufwand einsparen. Und drittens kannman so manche Frage auch direkt bei derAbstimmung beantworten und muss dafürdann gar nichts schreiben – wiederumgesparter Aufwand. Wichtig ist es auch, dieerarbeiteten Dokumenten-Templates denStakeholdern zum Review zu geben, umfrühzeitig Feedback zu erhalten und sounangenehme Überraschungen kurz vorder Inbetriebsetzung zu vermeiden.

Sieht das nach viel Aufwand für ein sol-ches Thema aus? Aus meiner Erfahrung,nein. Natürlich bekommt man die notwen-digen Informationen in der Regel nicht aufeinem Silbertablett serviert, sondern manmuss einen gewissen Klärungs- undAbstimmungsaufwand betreiben, wennman ein gemeinsames Verständnis herstel-len will. Das gleiche gilt für die Anfor -

26 27

4. Bündle die Themengebiete nach Inhal -ten und Zielgruppen in Dokumenten(Stichwort „Sichtweisen”).

5. Halte die Inhalte der Dokumente alsVerzeichnisstruktur mit kurzen Erläu -terungen je Kapitel fest („In diesemKapitel steht …”).

6. Gib die Dokumente mit den Ver -zeichnisstrukturen und Inhalten denStakeholdern zum Review.

Wichtig ist hierbei, dass das es sich um kei-ne Veranstaltung im stillen Kämmerleinhandelt, sondern dass diese sehr interaktiverfolgt. Sprechen Sie mit möglichst vielenParteien, um die relevanten Stakeholder zuermitteln. Es ist erstaunlich, wie häufig derFachbereich oder die IT-Entwicklung IhresAuftraggebers nicht wissen, wer alles inBetrieb und Wartung des beauftragtenSystems involviert ist. Nicht selten werdenSie regelrechte Aha-Erlebnisse bei IhrenAuftraggebern auslösen, wenn Sie dieStakeholder transparent machen.

Raten Sie nicht, welche Fragen dieStakeholder haben könnten. Sprechen Sie

Meine Empfehlung dafür ist eine stake-holder-basierte Analyse. Diese orientiertsich ebenfalls am agilen Mehrwert prin zip,indem sie den tatsächlichen Informa tions -bedarf systematisch erfasst und damit dieminimal notwendige Dokumenta tions -menge zu einem System definiert. Die sta-keholder-basierte Analyse orientiert sich andem zuvor beschriebenen IEEE-Standardund funktioniert folgendermaßen:

1. Identifiziere alle für die Inbetriebset zungsowie für Betrieb und Wartung relevantenStakeholder. (Ich betrachte die Inbetrieb -setzung ebenfalls, weil es häufig Doku -mente gibt, die notwendig sind, damit dasSystem eine Betriebs freigabe erhält, z. B.im Sicherheits- oder Datenschutzumfeld.)

2. Identifiziere die Fragestellungen dieserStakeholder. Dabei sollte nicht jedeEinzelfrage erfasst werden, sondern dieThemenfelder. Als Faustregel tut es inder Regel eine einstellige Zahl Frage -stellungen pro Stakeholder.

3. Leite aus den Fragestellungen Themen -gebiete für die Dokumentation ab.

schwerpunk t

Abb. 4: Schematisches Ergebnis einer stakeholder-basierten Analyse.

3/2011

derungen und alle anderen Infor mationen.Aber der Aufwand ist trotzdem recht über-schaubar: einige Gespräche, der Entwurfeiniger Dokumenten-Templates und nochein paar Abstimmungen. Das alles lässt sichin der Regel recht zügig erledigen.

Der Nutzen hingegen ist ungemeinhöher: Zum einen haben Sie Transparenzund ein gemeinsames Verständnis bezüglichder benötigten Systemdokumentation her-gestellt – an einer Stelle, die häufig nur vonAnnahmen und Halbwissen geprägt ist.Das führt auch schon zum zweiten Punkt:Durch das Eliminieren der Unsicherheit beiden benötigten Informationen können Sieden Umfang der geforderten Dokumen -tation stark reduzieren, weil häufig keinerso genau weiß, welche Informationenbenötigt werden, und deshalb sicherheits-halber alles dokumentieren lässt. Statt -dessen dokumentieren Sie jetzt nur nochdie wirklich benötigten Aspekte, die einenechten Mehrwert für Betrieb und Wartungliefern. Allein die hier möglichen Ein -sparungen rechtfertigen den Aufwand fürdie initiale Analyse.

Auch wenn Ihr Auftraggeber Ihnenschon – meist recht umfangreiche –Templates für die Systemdokumentationauf Basis seines Prozessmodells vorgibt,lohnt sich die Analyse in der Regel. So hat-te ich die Analyse in einem Projekt durch-geführt und es ergab sich daraus ein Bild,das dem Beispiel in Abbildung 4 recht ähn-lich war. Die Fragen einiger Stakeholderkonnten direkt geklärt werden, so z. B. dieder Systemplanung und des Sicherheits -beauftragten. Andere hatten gar nicht sohohe Dokumentationsanforderungen, wieinitial angenommen. Auf Basis der Analysekonnte die gemäß Prozessmodell eigentlich

erforderliche Dokumentation deutlichreduziert werden und aufgrund dergeschaffenen Transparenz war das auch füralle Beteiligten nachvollziehbar. DerZeitaufwand für die Analyse war imVerhältnis vernachlässigbar.

ZusammenfassungDamit haben Sie zwei einfache, agileWerkzeuge an der Hand, um eine für Sieund Ihr Projekt optimale Systemdoku -mentation zu schaffen: Dokumentations -vermeidung für die Projektdokumentationund stakeholder-basierte Analyse für dieSystemdokumentation. Man kann jetztbemängeln, dass das in Summe nichtsonderlich spektakulär ist, sondern nur

schwerpunk t

Literatur & Links

[Cun01] W. Cunningham 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, siehe: http://standards.ieee.org/findstds/standard/1471-2000.html

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

etwas, was man eigentlich sowieso machensollte, ausgerichtet an ein wenig agilemGedankengut. Dennoch habe ich immerwieder überrascht feststellen müssen, wieselten es in der Praxis so gemacht wird.Deshalb kann ich Sie nur dazu ermutigen,es in Ihrem nächsten Projekt zu versuchenund Ihre Erfahrungen damit zu sammeln.

Wie in fast allen Fällen gibt es auch fürgute Systemdokumentation kein Patent -rezept, weshalb ich Ihnen hier auch keinefertige Dokumentationsmenge anbietenkonnte. Es kommt immer auf Ihren genau-en Projektkontext an, aber allein durch die-se einfachen Werkzeuge haben Sie dieMöglichkeit, wesentlich näher an Ihre opti-male Systemdokumentation heranzukom-men. ■

OBJEKTspektrum ist eine Fachpublikation des Verlags:

SIGS DATACOM GmbH · Lindlaustraße 2c · 53842 TroisdorfTel.: 0 22 41 / 23 41-100 · Fax: 0 22 41 / 23 41-199 E-mail: info@sigs-datacom.dewww.objektspektrum.dewww.sigs.de/publications/aboservice.htm