Die leidige Dokumentation


13.11.2017 von

https://www.iteratec.de/fileadmin/Bilder/News/iteratec_logo.png https://www.iteratec.de/fileadmin/Bilder/News/iteratec_logo.png iteratec GmbH

Agile Entwicklung macht alles besser?

Die klassische Softwareent­wick­lung hat uns bei­ge­bracht, dass am An­fang die Do­ku­men­ta­tion steht – und in der Mitte und am Ende auch. Irgend­wie ist mit dieser Kon­zen­tra­tion auf Pro­zes­se und Arte­fak­te die eigent­liche Soft­ware etwas aus dem Fo­kus ge­raten. Mit dem Auf­kommen der agilen Ent­wick­lung wurde dieser Trend um­ge­kehrt – um nicht zu sagen ins Ge­gen­teil ver­kehrt. Doku­men­ta­ti­on hat in der agilen Ent­wick­lung eine deut­lich ge­ringere Bedeutung – wenn über­haupt. Diese Be­wer­tung steckt schon im „Agilen Ma­ni­fest“ [1]. Das wird auch durch Trends wie „Clean Code“ [2] auf­ge­griffen und verstärkt.

Im Folgenden wollen wir uns an­sehen, wo und wann wir Do­ku­men­ta­tion über­haupt noch brauchen und uns damit aus­ein­ander setzen sollten.

Dokumentation wozu?

Nach dem klassischen, wasser­fall­artigen Pro­jekt­vor­gehen ist Do­ku­men­ta­tion das Mittel, um ge­sam­mel­te In­for­ma­ti­o­nen zwischen den ver­schiedenen Projekt­phasen zu trans­por­tieren. Dabei kommt hinzu, dass oftmals Spezia­lis­ten bei­spiels­weise für die Auf­nahme der An­forde­rungen, das Design der Soft­ware, die Co­die­rung, den Test und den Be­trieb tätig werden.

So ein Vor­gehen ist ins­be­son­dere auch auf große und ver­teilte Pro­jekte aus­ge­legt. Das kann heißen, dass eine große Mann­schaft unter­wegs ist, um das Ziel bis zu einem fest­ge­legten Ter­min zu er­reichen. Das kann heißen, dass eine Mann­schaft lange Zeit an der Auf­nahme und Um­setzung der An­for­de­rungen arbeitet. Oder das kann bei­spiels­weise auch heißen, dass ein Pro­jekt die Codierung in einem Far­shore-Center durch­führen lässt.

Abbildung 1: Klassische Projekt­akti­vi­täten und Doku­men­ta­tionen

Essenziell dabei ist auch, dass die einzel­nen Pro­jekt­phasen im klassi­schen Vor­gehens­modell sequen­ziell durch­ge­führt werden. Dies ist in der Ab­bildung 1 illustriert. Da­zwischen gibt es Über­gabe­punkte. Ge­ge­benen­falls könnte das Ma­na­ge­ment sogar ent­schei­den, die späteren Pro­jekt­phasen nach hinten zu schieben oder sogar ganz von einer Fort­setzung abzusehen.

Die Do­ku­men­ta­tion spielt dabei eine ent­schei­dende Rolle, wenn es da­rum geht, die ein­zel­nen Pro­jekt­phasen mit­ein­ander zu ver­bin­den. Die in einer Pro­jekt­phase er­stell­te Do­ku­men­ta­tion ist essen­ziell in einer späteren Phase. Wenn wir uns bei­spiels­weise die Spezi­fi­ka­tion (auch Fach­kon­zept oder Pflichten­heft ge­nannt) an­sehen, so geht sie in das Design, die Ent­wick­lung und schließ­lich in den Test und die Ab­nahme der Soft­ware ein.

Das heißt ins­be­son­de­re, dass die Do­ku­men­ta­tion nicht aus­schließ­lich er­stellt wird, um einem Vor­gehens­modell Ge­nüge zu tun, son­dern dass es in jedem Fall auch einen Ver­braucher dieser Do­ku­men­ta­tion gibt. Das sollten wir uns als Leit­linie zu Eigen machen. Die Nütz­lich­keit einer Do­ku­men­ta­tion misst sich da­ran, ob und welche Ver­braucher, das heißt Leser, es gibt. Um­ge­kehrt können wir da­raus ab­leiten, dass Do­ku­men­ta­tion, die nicht ge­lesen wird, auch ver­zicht­bar ist.

Als Seiten­aspekt können wir uns auch wieder einmal in Er­inne­rung rufen, dass jede Doku­men­ta­tion so ge­schrieben werden sollte, dass sie den Leser opti­mal unter­stützt. So ist bei­spiels­weise ein roman­artiger Fließ­text für einen Leser, der punktu­ell ein­zel­ne Aspek­te ge­zielt nach­lesen muss, un­ge­eig­net. Das Gleiche gilt um­ge­kehrt auch für eine enzy­klo­pä­di­sche Samm­lung von Ein­zel­themen, wenn der Leser eine durch­gehende Ge­schichte er­wartet.

Ich sage es dir dreimal

Es gibt allerdings eine andere Über­legung, die uns dazu führen kann, Do­ku­men­ta­tion zu er­stellen, ob­wohl wir keinen di­rekten Leser ab­sehen können. Manch­mal steht das Thema Quali­tät im Vorder­grund und wir sind be­reit, dafür auch ent­sprech­ende In­ves­ti­tio­nen in Kauf zu nehmen.

Beispiels­weise ist im Be­reich der Luft­fahrt die Quali­tät di­rekt mit der Ge­fahr für Leib und Leben von Menschen ver­knüpft. Dem kommt man teil­weise so ent­gegen, dass es ein mehr­fache Re­dun­dan­zen gibt. Kritische Sys­teme im Flug­zeug oder der Flug­über­wachung sind drei­fach vor­han­den. Diese stam­men von ver­schiedenen Her­stellern und deren Er­geb­nisse werden ge­gen­ein­ander ab­ge­glichen.

Wir können dies ebenfalls auf die Soft­wareent­wick­lung können über­tragen. Die drei ver­schie­denen Blick­winkel finden wir in den unter­schied­lichen Ent­wick­lungs­arte­fakten wieder:

  • Anforderungen
  • Source-Code
  • Testfälle

Wenn alle drei Arte­fakte über­ein­stimmen, können wir sicherer sein, dass wir keinen Fehler in der Soft­ware haben, als wenn wird nur zwei oder gar nur den Source-Code als einziges Arte­fakt erstellen.

Technische Formate für Dokumentation

Im Laufe eines Projekts wird ge­ge­be­nen­falls Do­ku­men­ta­tion in ver­schie­dener Form ent­stehen. Am nahe­liegend­sten sind Do­ku­men­te, die in einer ge­wöhn­lichen Text­ver­arbei­tung er­stellt und gepflegt werden.

Entwickler sind oft­mals nicht be­son­ders an der Er­stel­lung von Do­ku­men­ten inte­res­siert. Die Er­stel­lung eines Pro­gramms ist da schon eher inte­res­sant.

„Papier ist ge­duldig – da kann ich ja jeden Un­fug auf­schreiben“

„Programme sind un­er­bitt­lich – da merke ich so­fort, ob etwas rich­tig funkti­o­niert“

Solche Aus­sagen sind typisch und spiegeln diese Ein­stellung wider. Da hilft es auch nicht, dass Do­ku­men­te außer­halb der ge­wohn­ten Ent­wicklungs­um­gebung be­arbeitet werden. Einige Alter­na­tiven nehmen in jüngerer Zeit an Be­deutung zu. Da sind zum Einen Wikis und Ticket-Sys­teme. Auf der ande­ren Seite werden Text­for­mate wie bei­piels­weise Mark­down [3] popu­lärer. Diese Alter­na­tiven zu den Text­ver­arbei­tungen lassen sich her­vor­ragend in eine Ent­wick­lungs­um­gebung inte­grie­ren. Da­mit wird zu­min­dest eine Hürde für die Ent­wick­ler beseitigt.

Trotzdem bleibt die Ab­nei­gung der Ent­wick­ler ge­gen­über Do­ku­men­ta­tion be­stehen. Das liegt nicht zu­letzt da­ran, dass die Fähig­keiten ver­mehrt in Rich­tung auf den Um­gang mit Code ge­übt und ge­fördert werden und weniger in Rich­tung auf Do­ku­ment­er­stel­lung. Ent­wickler werden selten zu Schrift­stellern – und um­ge­kehrt. Aber das ist eine andere Geschichte …

… und jetzt wird es agil

Wir haben spätes­tens mit dem agilen Mani­fest [1] ge­lernt, dass lauf­fähiger Code wich­ti­ger ist als Do­ku­men­ta­tion. In einem agilen Kon­text haben wir es aber weniger mit Spezia­lis­ten zu tun, die sich die Bälle zu­werfen, son­dern mit einem Team, das in enger Zu­sam­men­arbeit alle be­nötig­ten Fähig­keiten in sich ver­einigt. Die di­rekte Kom­muni­ka­tion zwischen Men­schen spielt die ent­schei­dende Rol­le. Das Wissen wird nicht in Do­ku­men­ten, sondern in den Köpfen der Be­teilig­ten aufbewahrt.

Immer mehr Unter­nehmen be­kennen sich zu einer agilen Ent­wick­lung. Nicht un­be­dingt, weil sie alle Werte ver­inner­licht haben und aus vollem Herzen be­jahen. Son­dern weil die Be­häbig­keit der alten Vor­gehens­weisen nicht mehr zu der Ge­schwin­dig­keit passt, die das „Business“ heute voran treibt. Hier ver­spricht ein agiles Vor­gehen deut­liche Besserung.

Abbildung 2: Agile Projekt­akti­vi­täten

In den agilen Vor­gehens­modellen gibt es keine großen Phasen. Die Akti­vi­tä­ten ge­schehen quasi para­llel eng ver­zahnt. Dies ist in der Ab­bil­dung 2 illus­triert. Da­mit wird eine Se­pa­rie­rung der Dokumentation in einzelne Typen, die als Wissens­über­gabe fun­gie­ren, wenig sinn­voll. Trotz­dem finden wir es immer wieder, dass in agilen Pro­jek­ten klassische Do­ku­men­ta­tion er­stellt wird – sei es als Teil der Sprints oder sogar in de­zi­dier­ten Doku­men­ta­ti­ons-Sprints.

Kontinuität in agilen Projekten

Eine der Vor­aus­setz­ungen in agilen Pro­jek­ten ist der Aspekt der Kon­ti­nui­tät. Dies wird leider immer wieder in den Hinter­grund ge­schoben. Des­halb ist es wichtig, uns dies in Er­inne­rung zu rufen und die Kon­se­quen­zen da­raus zu durchdenken.

Bei Scrum und im agilen Kon­text ist immer wieder von „Sprints“ die Rede. Diese sollten in der Regel zwei bis drei Wochen lang sein. Das heißt aber nicht, dass die Ver­weil­dauer eines Team­mit­glieds in dieser Länge ge­messen wird. Um­ge­kehrt ist es be­son­ders in solch einem Kon­text ent­schei­dend, dass das Team länger­fris­tig zu­sam­men bleibt und auch im Wesent­lichen in diesem Pro­jekt aktiv ist.

Mit der Kon­ti­nu­ität des Teams kann man auch auf das ge­mein­same Wissen in den Köpfen der Be­teilig­ten bauen. Die Do­ku­men­ta­tion wird weniger be­nötigt, um Wissen zu trans­por­tie­ren. In einem solchen Kon­text kann Do­ku­men­ta­tion bei­spiels­weise auch dazu dienen, ein­zel­ne As­pek­te zu durch­dringen, be­vor oder während man mit der Ent­wick­lung be­schäf­tigt ist. Das muss aber nicht heißen, dass alles und jedes aus­führ­lichst do­ku­men­tiert werden muss. Das Team sollte im Einzel­fall ent­scheiden, an welchen Stellen eine Do­ku­men­ta­tion sinn­voll ist und wie de­tail­liert diese sein soll.

Projektkonstellationen und ihre Auswirkungen

In den folgenden Ab­schnit­ten wollen wir drei Kon­stel­la­ti­onen in Pro­jekten be­trachten. Diese sind „in der freien Wild­bahn“ an­zu­treffen. Im Fokus steht dabei, wie die Kon­ti­nu­ität der Ent­wick­lung sich auf die Not­wen­dig­keit zur Do­ku­men­ta­tion aus­wirkt. Als Metapher ver­wen­den wir dabei Bilder aus der Leichtathletik.

Der Marathonläufer

Ein Projekt, das diesem Ideal nahe kommt, lässt sich mit einem Mara­thon­läu­fer im Sport ver­glei­chen. Das Team kann sich über längere Zeit hin­weg mit einer App­li­ka­tion be­fassen. Die Fluk­tu­a­tion ist ge­ring oder gleich Null. Das be­deutet kon­ti­nuier­liche Pflege und Weiter­ent­wick­lung. Da­mit haben wir natür­lich die ideale Si­tu­a­tion, in der der Wissens­er­halt im Team perfekt funk­ti­o­nieren kann.

In solch einer Situa­tion ist jegliche Do­ku­men­tation nur Zu­satz­auf­wand. Wer braucht denn die Do­ku­men­ta­tion, wenn das be­nötig­te Wissen schon im Kopf der Be­tei­li­gten vor­han­den ist? Hier haben wir es mit einer Do­ku­men­ta­tion zu tun, für die es keinen Leser gibt. Nach den oben ge­mach­ten Über­legungen, könnten und sollten wir auf solch eine Do­ku­men­ta­tion verzichten.

Der Staffellauf

Wenn die Situation nicht ganz so ideal läuft, dann können wir das viel­leicht mit einem Staffel­lauf im Sport ver­glei­chen. Die Kon­ti­nui­tät ist immer noch im Pro­jekt selbst. Aller­dings werden die Team­mit­glie­der – hoffent­lich moderat – aus­ge­tauscht. Da­mit kann das Wissen immer noch in den Köpfen der Be­teilig­ten vor­handen sein. Aller­dings werden regel­mäßig die neu hin­zu kom­menden Team­mit­glieder Wissen über­nehmen müssen. Dass es dabei zu Ver­lusten kommt, kennt jeder aus dem Spiel „Stille Post“.

In einem solchen Szenario ist es sinn­voll, Do­ku­men­ta­tion dazu ein­zu­setzen, um dem Stille-Post-Effekt ent­gegen­zu­wirken. Im Gegen­satz zu den vor­her gehenden Sze­na­rio haben wir hier eine klar de­fi­nier­te Leser­schaft vor uns. Jedesmal, wenn der Staffel­stab über­geben wird, kann der nächste „Läufer“ da­rauf zu­rück­grei­fen. Denn trotz aller guten Vor­sätze kommt bei einer münd­lichen Über­gabe immer irgend­etwas zu kurz. Das heißt, dass im Laufe der Zeit das an­fäng­lich vorhandene Wissen verloren geht, oder aufwändig wieder er­arbeitet werden muss.

Der Sprinter

Die nächste Kon­stel­la­tion, die wir uns ansehen wollen, können wir mit einem Sprinter ver­glei­chen. Auf einer kurzen Strecke wird die ganze Energie in­ves­tiert. Da­nach ist das Rennen vor­bei. Für ein Pro­jekt be­deutet das, dass schnell eine Appli­ka­tion aus dem Boden ge­stampft wird. Danach wird sie un­ver­ändert betrieben – oder auch nach re­la­tiv kurzer Zeit wieder außer Be­trieb ge­nom­men. So etwas habe ich bei­spiels­weise im Medien­be­reich er­lebt, wo die Halb­werts­zeit von (Web-)App­li­ka­ti­o­nen recht kurz ist.

In diesem Szenario gibt es keine Ver­braucher für Do­ku­men­ta­tion. Wozu sollte man in solch einer Si­tu­a­tion Do­ku­men­ta­tion er­stellen? Hier kann man gut und gerne darauf verzichten.

Der Sprinterkader

Eine Konstellation, die wir immer wieder be­obach­ten können, lässt sich viel­leicht mit Sprintern ver­glei­chen. Aller­dings nicht mit einem Ein­zel­nen, son­dern mit einer ganzen Mann­schaft. Nach­dem ein Ren­nen statt­ge­funden hat, stellen sich nach einiger Zeit andere Läufer auf, um auch noch ein Rennen auf der gleichen Bahn zu laufen.

Im Projekt­alltag heißt das, dass in eher kürzeren Pro­jek­ten je­weils neue App­li­ka­ti­o­nen für eine An­wen­dungs­land­schaft er­stellt oder be­stehende App­li­ka­ti­o­nen weiter ent­wickelt werden. Die Mann­schaft re­kru­tiert sich dabei oft­mals aus einem Ent­wickler-Pool. Damit ist die Kon­ti­nu­i­tät in der Regel nicht gewährleistet.

Der Einsatz eines Ent­wick­ler-Pools mag zwar für die Aus­las­tung und die Flexi­bi­li­tät der ge­sam­ten Ent­wick­ler­truppe opti­mal sein. Aber das bringt auch mit sich, dass zwischen den ein­zel­nen Phasen von Akti­vi­tät je­weils ein Bruch ent­steht. In solch einem Sze­na­rio ist Do­ku­men­ta­tion un­er­läss­lich, um das Wissen über die App­li­ka­tion zu be­wahren und an die nächste Ge­ne­ra­tion weiterzugeben.

Fazit

Die Kritikali­tät und die Kon­ti­nu­i­tät in einem Pro­jekt sind die ent­schei­den­den Schlüs­sel, anhand derer wir die Sinn­haftig­keit von Do­ku­men­ta­tion be­wer­ten können. Kritische App­li­ka­ti­o­nen oder zer­stückel­te Ent­wicklung sprechen für eine aus­führ­liche Do­ku­men­ta­tion. Konti­nu­ier­liche Ent­wick­lung und ge­ringere An­for­de­rungen an die Quali­tät können uns dazu bringen, auf eine exzes­sive Do­ku­men­ta­tion zu­gun­sten der Kosten­ein­sparung und des Time-to-market zu ver­zichten. Agile Ent­wick­lung alleine ist kein guter Grund, auf Dokumentation zu verzichten.

Mit diesem Mittel werden wir in die Lage ver­setzt, zu ent­scheiden, wie­viel Ener­gie wir in die Do­ku­men­ta­tion stecken sollten und müssten. Auf der an­deren Seite helfen uns diese Kri­te­rien aber auch zu argu­men­tie­ren, wo und wa­rum wir auf Do­ku­men­ta­tion eher ver­zich­ten können. Da­mit kommen wir hoffent­lich zu einem Kom­pro­miss, der nicht nur von Ge­horsam ge­gen­über alt­her­ge­brach­ter Ge­pflogen­heiten ge­tragen wird. Statt­dessen sollte die Einsicht in die Not­wen­dig­keit und Nütz­lich­keit im Vor­der­grund stehen. Eine von allen Pro­jekt­be­tei­lig­ten ge­teilte Ein­schätzung hilft schließ­lich auch, die Mo­ti­va­tion bei allen hoch zu halten.

Referenzen

[1] Manifesto for Agile Software Development http://agilemanifesto.org/
[2] Robert C. Martin: Clean Code: Refactoring, Patterns, Testen und Techniken für sauberen Code.
mitp-Verlag, ISBN 978-0-13-235088-4.
[3] Markdown, Wikipedia.

Dieser Blog-Artikel steht under der Lizenz CC-BY-SA 4.0.
Die in den Blog-Beitrag eingebundenen Bilder stammen zum Teil von Pixabay und stehen alle unter der Lizenz CC-0.

Diesen Artikel bewerten
 
 
 
 
 
 
 
7 Bewertungen (63 %)
Bewerten
 
 
 
 
 
 
1
5
3.15
 

Artikel im Warenkorb:

0