METHODE


Methode

cards+ ist eine agile Methode

cards+ unter­­stützt eine Pro­jekt­­­organi­­sation, Wissens­­manage­ment in einem agilen Ent­wick­­lungs­­­pro­jekt rich­­tig zu organi­­sieren. Der Pro­dukt­verant­­wort­liche setzt cards+ ein, um ziel­­­gerich­­tet und inkre­men­tell sein Pro­dukt ange­messen zu doku­men­tieren, unter­stützt durch ein selbst­organi­sier­tes Team.

Es gilt die Prä­­misse, dass eine ange­messene Pro­dukt­doku­men­tation not­­wendig ist. Eine sol­che Pro­dukt­doku­men­tation wächst mit dem Pro­dukt. Sie ist ein Ergeb­nis des agi­len Ent­wick­lungs­­pro­zesses. Sie muss daher mit dem glei­chen Maß­stab für die Quali­tät, mit dem glei­chen Ansatz für empi­­rische, inkre­men­­telle und itera­tive Arbeits­weise und mit den glei­chen Wer­ten herge­stellt wird, wie auch das Pro­dukt ent­­wickelt wird. An die­sem Punkt kommt die Methode cards+ ins Spiel.

Doku­mente wer­den agil ent­wickelt.

cards+ tritt mit dem Ver­­spre­chen an, die Erstel­lung und Pflege einer quali­tativ hoch­wer­tigen Pro­dukt­­doku­men­tation in einem Wiki zu ermög­­lichen. Viele Prinzi­­pien und Prak­­tiken der Ent­wick­ler gel­ten auch für Autoren in einem Wiki, in den meis­ten Fäl­len in nur leicht abge­wandel­ter Form.

cards+ ist kein geschlos­senes Vor­­gehens­­modell, kein iso­lier­ter Pro­zess. Aus diesem Grund kann cards+ sehr gut in beste­hende Pro­zesse inte­griert wer­den. Autoren im Wiki planen und steuern ihre Tätig­kei­ten weiter­hin mit Tech­niken aus dem Pro­jekt­­manage­ment. Sie ver­wenden die Methode ihrer Wahl für die Anfor­derungs­­ana­lyse. cards+ ist als zusätz­liches Werk­zeug für Autoren zu ver­­ste­hen, mit dem sie ihre Ergeb­nisse im Wiki organi­sieren.

Für Leser ist cards+ die Chance, im Wiki jede rele­vante doku­men­tierte Infor­mation zum Pro­dukt zu fin­den. Das Wiki unter­stützt sie durch die Ver­knüpfung von Seiten, die Kate­gori­sierung der Seiten mit Stich­wor­ten und umfang­reiche Such­funktio­nen.

Doku­­men­tation agil ent­­wickeln.


Prin­zi­pien

Pro­­fessio­­nell visu­­ali­­sie­­ren

Visu­ali­sie­rung hilft, kom­plexe Zusam­men­hänge zu ver­deut­lichen. Durch gut gemachte Bil­der wird die Auf­merk­sam­keit der Leser deut­lich erhöht. Es ent­steht eine gemein­same Sprache: Die Bild­sprache. Wich­tige Begriffe werden sicht­bar. Sie bekom­men ein «icon» mit hohem Wieder­erken­nungs­wert. Der Kompo­nenten­über­blick gibt — wie der Name schon sagt — einen Über­blick über die Kompo­nenten des IT-Sys­tems. Die Abbil­dung zeigt abstrakt Dienste und Daten­flüsse und zieht Gren­zen. Hier wird deut­lich, dass cards+ und Domain-Driven Design (kurz DDD) sehr ähn­liche Ansätze ver­fol­gen.

Das wich­tigste Element im stra­tegi­schen Design von DDD ist die Kon­text­grenze (engl. bounded context), rein formell eine Gültig­keits­grenze für ein fach­liches Modell einer Domäne. Domänen unter­schei­den sich in ihrer Rele­vanz für den Erfolg des IT-Systems. DDD unter­scheidet wich­tige Domänen (engl. core domains), die den Unter­scheid machen, und unter­stützende Domänen (engl. generic domains), für die es häufig Stan­dard­lösungen gibt. Die Kontext­land­karte (engl. context map) ist eine abstrakte Sicht auf alle Domänen des IT-Systems. Wechsel­wirkungen und die Ein­fluss­nahme von Domänen unter­einan­der werden durch eine Reihe von Inter­aktions­arten doku­men­tiert. Im tak­tischen Design von DDD gibt es die Grund­elemente Service, Event, Entity und Value. Für die Modellierung kom­plexer Daten­struk­turen gibt es das Ele­ment Aggregate.

cards+ erfin­det DDD nicht neu. cards+ ist ein Ange­bot, ein agiler Ansatz, um die Ergeb­nisse der Modellierung aus dem DDD in einem Wiki zu sichern. Im stra­tegi­schen Design kann der Kompo­nenten­über­blick von cards+ mit der Kon­text­land­karte von DDD gleich­gesetzt werden. Kon­text­grenzen werden durch den Bau­stein Domain reprä­sen­tiert. Im tak­tischen Design mit DDD ist cards+ eine opti­male Ergän­zung. DDD legt dabei das Vor­gehen bei der Ana­lyse fest. Für die Beschrei­bung der Ergeb­nisse gibt es passende Bau­stei­ne bei cards+. Der Bau­stein Entity wird für die Ele­mente Value, Aggre­gate und Entity ver­wendet. Für die Ele­mente Service und Event gibt es die gleich­namigen Bau­steine Service und Event.


Prin­zi­pien

Pro­­fessio­nell doku­men­­tie­­ren

Doku­mentieren ist ein erlern­bares Hand­werk. Prinzi­pien der Methode cards+ unter­stützen die Autoren dabei. Ihre prak­tische Umsetzung ist ein wich­tiger Teil der Methode.

Scrum oder XP haben die Arbeits­weise der Ent­wick­ler nach­hal­tig ver­ändert. Die Initia­tive der »clean code developer« bein­hal­tet einen Kata­log von Prinzi­pien und Prak­tiken für mehr Pro­fessio­nali­tät in der Soft­ware-Ent­wick­lung. Als Hilfe­stel­lung bekom­men Ent­wick­ler ein Werte­sys­tem, an dem sie sich orien­­tie­ren können. Das gilt auch für das Doku­men­tie­ren im Wiki. Die glei­chen Prinzi­pien machen auch die Arbeit von Autoren besser.

COD

»Con­vention over docu­mentation« hat das Ziel, Doku­­men­tation durch Kon­ven­­tionen zu ver­­mei­den oder zu redu­­zie­ren.

DOD

Eine »Defi­nition of done« ver­kör­pert ein expli­zites und geteil­tes Ver­­ständ­nis davon, unter wel­chen Bedin­gun­gen ein Pro­dukt fer­tig ist.

DRY

»Don´t repeat your­self« hat zum Ziel, jede unnö­tige Wieder­­holun­gen von Inhal­ten im Wiki zu ver­­mei­den.

INVEST

»Invest in good stories« defi­­niert sechs Kri­­terien, die uns hel­fen, fach­­liches Wissen so kom­pakt und voll­­stän­dig wie mög­­lich zu ver­­mitteln.

KISS

»Keep it simple, stupid« besagt, dass wir eine mög­­lichst ein­­fache Beschrei­­bung für Inhalte wäh­len sollen. »Weniger ist mehr« sagt schon ein Sprich­­wort. Ein­fach­heit ist die Kunst, die Menge nicht geta­ner Arbeit zu maxi­mieren.

PLA

»Prin­ciple of least astonish­ment« spie­gelt sich im Auf­bau der Seiten im Wiki wider. Jeder Bau­stein hat genau einen Zweck, fest­gelegte Abschnitte und ist das Ergeb­nis eines bestimm­ten Pro­zesses.

SLA

»Single level of abstraction« spie­gelt sich in der Struk­­tur des Wiki wider. Für jede Seite ist klar defi­­niert, was in einer Seite beschrie­ben wird und was nicht in diese Seite gehört.

SOC

»Sepa­ration of con­cerns« führt dort zu einer Tren­nung fach­­licher und tech­­nischer Doku­­men­tation, wo es Sinn macht.

SRP

»Single responsi­bility prin­ciple« regelt die Ver­antwor­tung für den Inhalt im Wiki. Eine Seite hat immer genau einen Autor. Er ist für den Inhalt der Seite ver­ant­wort­lich, bis sie “fertig” ist.

Kommen­tare erfol­greich moderie­ren.


Prak­­tiken

Konti­nuier­lich ver­bessern

Wie beim Pro­gram­­mieren gehört die Anwen­­dung der Pfad­finder­regel auch beim Doku­men­tieren zum Funda­ment pro­­fessio­neller Arbeit. Leser können jeder­­zeit einen ent­spre­chen­­den Hin­­weis als Kommen­­tar in der Seite hin­ter­lassen. Autoren grei­­fen diese Hin­weise wert­schätzend auf. Nach dem Abschluss der Ver­­besse­­rung wird der Kommen­­tar gelöscht.

Jeder Autor im Wiki kann bereits beim aktiven lesen einer beliebigen Seite kleine, aber wich­­tige Korrek­turen durch­füh­ren. Kleine Korrek­turen sind bei­spiels­weise die Ver­besse­rung von Recht­schreib­­feh­lern oder die Ver­knüpfung von Begriffen im Text mit Ein­trägen im Glossar. Durch diese eben­falls recht ein­fache Maß­nahme erkennt der Autor auto­matisch wieder­holt auf­tre­tende Erklärun­gen im Text, die er ohne Ver­lust von Wissen­ aus der Seite ent­fernen kann. Gege­­benen­falls ergänzt er Schlag­worte in der Seite. Schlag­worte sind Begriffe aus einem kontrol­lier­ten Voka­bular. Bei cards+ wird dieses Voka­bular durch das Glossar defi­niert. Mit dieser Maß­nahme wird die Suche im Wiki für Leser deut­lich ver­bessert.


Prak­­tiken

Ziel­gerich­tet ver­bessern

Code-Reviews sind beim Pro­gram­­mieren nicht mehr weg­zuden­ken. Das Vor­gehen eig­net sich nicht nur dazu, die Quali­tät der Soft­ware zu ver­bessern. Es unter­stützt auch den Wissens­trans­fer inner­halb des Teams. Das Gesagte gilt auch für das Doku­men­tieren mit cards+. Bei der Durch­führung eines Reviews einer Seite im Wiki prüft der Reviewer sowohl die Richtig­keit als auch die Voll­ständig­keit der Inhalte.

Die Rich­tig­keit der Seite schätzt der Reviewer anhand seines eigenen Wissens ein. Die Ver­knüpfung von Begrif­fen im Text mit Ein­trä­gen im Glossar unter­stützt ihn dabei. Beim Lesen korri­giert er offen­sicht­liche Feh­ler in der Recht­schrei­bung. Der Editor des Wiki hilft dabei. Bei allen anderen Feh­lern oder Lücken nutzt er die Kommen­tar­funk­tion, um Hin­weise für den Autor in der Seite zu hinter­lassen.

Eine Seite ist voll­stän­dig, wenn

  • die vor­bereitete Seiten­vor­lage des Bau­­steins ver­wen­det wurde.
  • alle Abschnitte aus der Seiten­vor­lage des Bau­­steins ausge­füllt sind.
  • passende Schlag­worte in der Seite gesetzt sind.

Diese rein for­malen Prüfun­gen sind mög­lich, weil die Seiten­vor­lagen einen festen Rah­men für jeden Bau­stein vor­geben.


Prak­­tiken

Konti­nuier­lich ver­öffent­lichen

Ein Wiki ist opti­mal geeig­net für die Erfas­sung, Pflege und vor allem Präsen­tation von Pro­dukt­wissen. Die Pflege von Seiten direkt im Wiki kommt dort an seine Gren­zen, wo regel­mäßig und in kurzen Abstän­den Ver­ände­rungen gemacht werden. Das ist vor allem dort der Fall, wo eine Lösung für eine Fähig­keit der Soft­ware von den Ent­wick­lern sehr genau beschrie­ben wird. Diese Art doku­men­tier­ter Infor­mationen sind ganz eng an die Imple­men­tierung gekop­pelt und werden in der Konse­quenz zusam­men mit dem Code ver­sio­niert.

In einer Spezifi­kation halten Ent­wick­ler die Struk­tur eines Objek­tes, Geschäfts­regeln und Algo­rith­men eines Dienstes oder den Auf­bau und das Ver­hal­ten einer Bedien­ober­fläche fest. cards+ macht keine Vor­gaben für eine Spezifi­kation. Mit der Frei­gabe der Soft­ware für das Pro­dukt­inkre­ment wird jede damit ver­bun­dene Spezifi­kation im Wiki in den Bau­steinen Service, Entity, Event oder Layout ver­öffent­licht.

Eine ähn­liche Situa­tion gibt es bei den Test­plänen in einer Test­pyra­mide. Die Test­fälle eines System­tests sind sehr gut als zusätz­liche Doku­men­tation geeig­net, wenn sie sich an den Fähig­keiten der Soft­ware orien­tie­ren. cards+ macht keine Vor­gaben für einen Test­plan. Mit der Frei­gabe der Soft­ware für das Pro­dukt­inkre­ment werden die durch­geführ­ten Test­fälle im Wiki ver­öffent­licht. Abhän­gig vom Auf­bau der Test­pläne bieten sich die Bau­steine Epic oder Case an.

Sowohl Spezifi­katio­nen als auch Test­pläne sind wie Code Teil des Pro­dukt­inkre­men­tes und damit ein Ergeb­nis des Teams. Es ist Auf­gabe des Teams, für die doku­men­tier­ten Infor­matio­nen ein geeig­netes For­mat zu wäh­len, das im Wiki ver­öffent­licht werden kann. Am besten auto­mati­sier­bar.


Prak­­tiken

Konti­nuier­lich schät­zen

Der Pro­dukt­verant­wort­liche hat eine Vision des Pro­duk­tes. Den Bau­stein Epic gibt einer ange­­for­der­ten Funktio­­nali­tät des Pro­duk­tes einen ein­­deu­tigen Namen und grup­piert die neuen Fähig­keiten der Soft­ware. Den Bau­stein Case legt er an, um jeder neuen Fähig­keit der Soft­ware einen Titel zu geben und die Aus­gangs­lage kurz zu beschrei­ben. Die Lösung bleibt auf jeden Fall offen. Kann der Pro­dukt­verant­wort­liche mit seiner Vision einen Auf­trag­geber begeis­tern, bekommt er häu­fig die Frage gestellt, was das den unge­fähr kos­tet. Agil hin oder her, er braucht eine realis­tische Zahl, an die er selbst glaubt. Für eine Exper­ten­schät­zung durch sein Team muss er sehr viel Arbeit in das Back­log inves­tieren. Und selbst dann ist die Schät­zung in der Regel mit einer hohen Unge­nauig­keit ver­bun­den.

cards+ eröff­net eine neue Option mit dem Ein­satz der Schätz­methode »Use-Case-Points« von Stephan Frohnhoff. Der Bau­stein Case erfüllt alle Bedin­gungen als Ein­gangs­größe für die Schätz­methode. Jeder Case wird auf einer Skala von ein­fach, nor­mal oder kom­plex mit Punk­ten bewer­tet. Die Punkte aller Fähig­keiten der Soft­ware werden addiert und mit Fak­toren gewich­tet. Es gibt Fak­toren für tech­nische Kom­plexi­tät, das Pro­jekt­umfeld und die Pro­duktivi­tät des Teams. Das Ergeb­nis sind Per­sonen­stunden. Der geschätzte Wert ist natür­lich mit einer Unge­nauig­keit ver­bun­den. Mit der Reali­sierung von Fähig­keiten kann die Schät­zung kali­briert werden.

Der Pro­dukt­verant­wort­liche wird in die Lage ver­setzt, die die Schätzung konti­nuier­lich zu aktuali­sie­ren. Fügt er einen neuen Bau­stein Case hinzu, ergänzt er die Schätzung um eine Bewer­tung der neuen Fähig­keit der Soft­ware. Er orien­tiert sich dabei an den bereits vor­hande­nen Fähig­keiten. Der Auf­trag­geber bekommt in sehr kur­zer Zeit eine erste grobe Indi­kation der Kos­ten für die Reali­sierung.

Doku­men­tation nach­hal­tig organi­sie­ren.


Methode

Pro­fessio­nell zusamm­men­arbei­ten

Jede an einem IT-System inter­essierte Par­tei hat ihre eigene Vor­stel­lung von guter Doku­men­tation. Diese Vor­stellung ist ganz maß­geb­lich von ihren per­sön­lichen Schwer­punk­ten bestimmt. »Viele Köche ver­der­ben den Brei« ist ein Sprich­wort, das wahr wird, wenn jede an der Pro­dukt­doku­men­tation be­teilig­te Per­son so schreibt, wie sie es aus per­sön­licher Sicht für rich­tig hält. Leser und Auto­ren brau­chen ein Grund­gerüst, an dem sie sich orien­tie­ren können. cards+ bie­tet dafür die feste Struktur mit den Berei­chen Sys­tem­be­schrei­bung, Sys­tem­struk­tur und Archi­tekur­ent­wurf. In jedem Be­reich gibt es vor­defi­nierte Bau­stei­ne mit festem Auf­bau.

cards+ unter­schei­det drei Rollen, die wesent­lich zum Gelin­gen einer Pro­dukt­doku­men­tation bei­tra­gen: Leser, Autoren und Gärtner. Auf­grund der Tren­nung von Doku­men­tation im Wiki und Spezifi­kation durch das Team im Code-Reposi­tory bezieht sich die Defi­niton der Rollen von cards+ nur auf die Per­sonen, die direkt im Wiki arbei­ten.

Alle Gärtner und Ver­tre­ter der Autoren sind Teil einer Exper­ten­runde (engl. community of practice) und Spre­cher der Ziel­gruppen der Pro­dukt­doku­men­tation.

Leser

Leser ist jede am Pro­dukt inter­essierte Par­tei. Ein Leser nutzt das Wiki als Hilfs­mittel zur Erfül­lung seiner Auf­gaben im agilen Ent­wick­lungs­pro­zess. Das Wiki ist für ihn eine unver­zicht­bare Quelle für Pro­dukt­wissen. Jeder Leser ist berech­tigt, im Wiki Sei­ten zu lesen und zu kommen­tie­ren.

Autor

Der Pro­dukt­verant­wortliche ist Autor. Analys­ten, IT- und UX-Exper­ten, Redak­teure und Ver­treter des Teams unter­stützen ihn als Co-Autoren. Ein Autor ist berech­tigt, neue Seiten im Wiki anzu­legen und beste­hende Seiten zu ändern oder zu löschen. Seine Auf­gabe ist es, Seiten im Wiki inkre­mentell mit Pro­dukt­wissen zu füllen.

Gärtner

Ein Gärtner ist Experte für Doku­men­tation und Adminis­tra­tor für das Wiki. Er ist ver­ant­wort­lich für die Aus­wahl der Werk­zeuge für die Autoren. Als Trainer für cards+ ist er für Autoren und Leser greif­bar und hilft ihnen bei der Bewälti­gung von all­täg­lichen wie auch spezi­ellen Prob­lemen im Zusam­men­hang mit Doku­men­tation.


Methode

Doku­menta­tion agil ent­wickeln

Die Werte aus dem Mani­fest für agile Soft­ware-Ent­wick­lung bil­den das Funda­ment agiler Ent­wicklung. Mit cards+ kann auch Doku­mentation agil ent­wickelt werden. Agil Doku­mentieren bezeich­net ein schritt­weises Erfas­sen von Ent­schei­dungen und Wissen in einem agilen Ent­wicklungs­prozess. Die Struk­tur der Produkt­doku­mentation ist so gestal­tet, dass Ergeb­nisse schritt­weise mit einem geeig­neten Bau­stein gesichert werden kann. Autoren schrei­ben nur das auf, was sie jetzt wissen. Keine Wünsche. Keine Vermutungen.

Aufgrund der maß­geschnei­derten Struk­tur können Auto­ren trotz­dem jeden Bau­stein in kurzer Zeit abschlie­ßen. Eine wich­tige Bedingung für ein agi­les Ent­wick­lungs­pro­jekt, um Doku­men­tation als ein weiteres Ergeb­nis einer Iteration zu fordern. Bei agiler Ent­wick­lung mit Scrum kann ein Pro­dukt­ver­ant­wort­licher die Regel­ter­mine von Scrum nutzen, um Feed­back auch zur Pro­dukt­doku­men­tation einzu­sam­meln. Mit dem Ein­satz von cards+ gilt:

Doku­mentation wird wie Code ent­wickelt!

Eine Pro­dukt­doku­men­tation hat eine innere Struk­tur. Sie besteht aus Bau­stei­nen mit einem klar formu­lierten und prüf­baren Inhalt. Es bietet sich ganz ein­fach an, die Pro­dukt­doku­men­tation im gleichen agi­len Pro­zess zu schrei­ben, in dem auch das Pro­dukt pro­gram­miert und getes­tet wird.

Eine Pro­dukt­doku­men­tation wird über die gesamte Lebens­zeit eines Pro­duktes gebraucht. Bei sehr erfolg­reichen Pro­dukten sind das Jahr­zehnte. Ein Pro­dukt ent­steht oder wächst, indem Visi­onen und Ideen eines Pro­dukt­verant­wort­lichen durch sein Team in Soft­ware trans­formiert werden. Test­pläne, organi­siert in einer Test­pyra­mide, sichern die Quali­tät der Soft­ware ab. Hand­bücher geben Ein­blick in die Fähig­keiten der Soft­ware, erklären den Nutzern, wie sie ver­wendet werden. In den Bau­stei­nen der System­beschrei­bung wird der Pro­blem­raum des Pro­duktes beschrie­ben. Sie geben Ant­wort auf die Fra­gen wer, wann und warum etwas mit dem Pro­dukt tut. Die Bau­steine der System­beschrei­bung beant­worten hin­gegen die Frage, wie das Pro­dukt reali­siert wurde. Zusam­men mit den Bau­steinen des Archi­tektur­ent­wurfs beschrei­ben sie den Lösungs­raum.

Eine Pro­dukt­doku­men­tation hat das Ziel, den Zustand eines Pro­dukt­inkre­mentes so exakt wie mög­lich zu beschrei­ben. Sie exis­tiert im Wiki und wird genutzt, um Spezifi­kationen und Test­pläne zu ver­öffent­lichen. Sie bildet das zen­trale Ver­zeich­nis der für das Pro­dukt rele­vanten Doku­mente.


Methode

Doku­mente nach ihrer Art unter­scheiden

Eine einiger­maße komplexe Soft­ware ohne Doku­men­tation ist für mich nicht vor­stell­bar. Ein Pro­dukt­verant­wort­licher kann oder besser muss sich über den Pro­zess der Erstel­lung einer Pro­dukt­doku­men­tation Gedan­ken machen. Im all­gemeinen Sprach­gebrauch werden Doku­mente geschrie­ben. Mit cards+ werden Doku­mente ent­wickelt. Das geht aber nicht mit jeder Art von Doku­ment.

Eine Pro­dukt­doku­men­tation ist unver­zichtbar für das Auf­recht­erhal­ten des agilen Ent­wick­lungs­prozesses und unter­stützt die Kommuni­kation in der Pro­jekt­organi­sation. Sie beschreibt Ergeb­nisse. Abstim­mungen führen zu Ent­schei­dungen. Anfor­derungen werden ana­lysiert und umge­setzt oder abge­lehnt. Auf­gaben werden erle­digt, damit ein neues Pro­dukt­inkre­ment ent­steht.

Der Begriff Pro­jekt­doku­men­tation fasst jene doku­men­tierte Infor­matio­nen zusam­men, die für das Auf­recht­erhal­ten von Pro­zessen, also Pla­nung und Steue­rung von Auf­gaben, not­wen­dig sind. cards+ bietet für die Pro­jekt­doku­men­tation kei­nen Bau­stein! Die Arten­viel­falt ist ein­fach zu groß. Die Bedürf­nisse der inter­essier­ten Par­teien sind zu unter­schied­lich. Die Lebens­dauer der Doku­mente ist oft zu gering für einen wirt­schaft­lich ver­tret­baren An­satz zur Stan­dardi­sie­rung.


Defini­tion

Was zählt zur Projekt­doku­mentation?

Auf­gabe

Für die Erfas­sung und Steue­rung von Auf­gaben in einem Back­log bietet cards+ keinen Bau­stein an. Mit den Bau­steinen von cards+ wird jedoch wich­tiges Wissen für eine Auf­gabe recht­zeitig und struktu­riert in der Produkt­doku­mentation vorbe­reitet.

Anfor­derung

Die Ver­waltung und Bewer­tung einer Anfor­derung ist nicht Teil der Methode cards+. Das Ergeb­nis der Anfor­derungs­analyse wird jedoch mit den Bau­steinen Topic, Epic und Case ange­messen in der Produkt­doku­mentation doku­mentiert.

Abstim­mung

Im Projekt­alltag finden laufend Abstim­mungen statt. Jede Abstim­mung mit großer Trag­weite führt zu einer begrün­deten Ent­schei­dung, die es wert ist, nach­haltig doku­mentiert zu werden. cards+ bietet dafür den Bau­stein Decision an.

Richt­linie

Eine Richt­linie ist eine Verein­barungen, die die Zusammen­arbeit im Ent­wicklungs­projekten und in den Teams regelt. Ist die Richt­linie rele­vant für das Produkt, kann sie natür­lich mit den Bau­stein Spec für Kon­zepte in die Produkt­doku­mentation aufge­nommen werden.

Lasten­heft

In der agilen Welt unge­liebt, aber häufig not­wendig, um ein Gewerk zu präzi­sieren und einen Ver­trag zu schließen. Mit cards+ erstellen wir inkre­mentell eine System­beschrei­bung mit den Bau­steinen Topic, Epic und Case. Die gleichen Bau­steine können wir als Lasten­heft aus dem Wiki expor­tieren. Jeder­zeit.

Experten­schätzung

Schätzen ist ein sehr häu­fig sehr kontro­vers disku­tiertes Thema in Ent­wick­lungs­pro­jek­ten, beson­ders in agi­len. Der Bau­stein Case ist eine geeig­nete Basis für die Schätz­methode »Use-Case-Points« von Stephan Frohn­hoff. Sie lässt sich prak­tisch direkt ein­setzen.


Methode

Kommen­tare erfolg­reich mode­rieren

Die Methode cards+ ver­folgt ein sehr wich­tiges Ziel. Eine leben­dige Pro­dukt­doku­mentation. Sie lebt u.a. durch das Feed­back der Leser. Feed­back als Kommen­tare in den Seiten des Wiki ist für alle sicht­bar, auch eventuell daraus ent­stehende Diskus­sionen. Feed­back ist jeder­zeit will­kommen. Die Erstel­lung und Pflege von Inhalten im Wiki ist Auf­gabe der Autoren. Dazu gehört auch die Mode­ration der Kommen­tare der Leser in den Seiten. Im Sinne der Nach­haltig­keit entfernt der Autor einer Seite Kommen­tare, die bereits zur Korrek­tur der Doku­mentation ver­wendet wurden. Nicht mehr rele­vante oder sachlich nicht korrekte Kommen­tare löscht er nach Abschluss der Klärung mit dem Ersteller des Kommen­tars. Durch dieses aktive Manage­ment der Kommen­tare schaffen wir Transpa­renz bei den Änderungen der Inhalte. Autoren können Kommen­tare auch als Indi­kator für die Quali­tät der Doku­mentation heran­ziehen.

Eine Seite im Wiki, die keine Kommen­tare enthält, ist darum eine gute Seite.

Anderer­seits ist eine Seite im Wiki mit Kommen­taren schlicht und ein­fach nicht fertig. Sehr viele Kommen­tare aus einer von mehreren Lesern kontro­vers geführten Diskus­sion sind ein klares Indiz für den Autor, das Thema der Seite noch einmal inten­siver zu betrach­ten.


Defini­tion

Welche Kate­gorien von Kommen­taren gibt es?

Verbesserung

Leser nutzen einen Text­kommen­tar, um eine redaktio­nellen Ver­besserung zu melden. Dazu zählen Recht­schreib- oder Grammatik­fehler in einem Text. Auch eine fehlende Ver­knüpfung eines Begriffes im Text mit einer Seite im Glossar ist hier gemeint. Die Korrek­tur der Seite kann ein Autor jeder­zeit und ohne umfang­reiche Abstimmung durch­führen.

Lücke

Eine interessierte Partei (z.B. ein Nutzer) findet als Leser eine Lücke in einer Beschrei­bung finden und meldet sie als Seiten­kommen­tar. Bei einer Lücke reden wir nicht von einem Fehler. Trotzdem ist jeder Hin­weis sehr will­kommen, wenn er einem Autor hilft, die Beschrei­bung besser zu machen. Die Korrek­tur der Seite kann ein Autor jeder­zeit nach erfolg­reicher Prüfung durch­führen.

Offener Punkt

Eine inter­essierte Partei (z.B. ein Ent­wickler) hat den Ein­druck, dass eine Beschrei­bung nicht voll­ständig ist. Solche Unklar­heiten bezeichnen wir als offene Punkte, bis sie geklärt sind. Offene Punkte ver­sucht der Autor der Seite so rasch wie mög­lich zu klären. Das Ergeb­nis der Klärung nutzt der Autor, um den Inhalt der Seite zu ver­bessern.

Fehler

Eine inter­essierte Partei (z.B. ein Ent­wickler) hat den Ein­druck, dass eine Beschrei­bung offen­sichtlich fehler­haft ist. Die Ein­schätzung ist subjek­tiv, bedeutet aber, dass die kommen­tierte Seite nicht mehr fertig ist. Fehler muss der Autor der Seite so rasch wie mög­lich klären. Das Ergeb­nis der Klärung nutzt der Autor, um den Inhalt der Seite zu ver­bessern.


Methode

Der Gärtner trägt Verant­wortung

Es gibt das Phäno­men, dass intelli­gente Menschen gegen Regeln ver­stoßen, obwohl sie von ihrer Wirk­sam­keit im Allge­meinen über­zeugt sind. Trotz­dem vertei­digen sie die Abweichung von der Regel mit dem Argu­ment, dass es eine not­wendige Ver­besserung oder gar Inno­vation ist. Manche tun es sogar im guten Glau­ben, dass ihr Weg besser ist, diese Änderung schon lange not­wen­dig war. Das ist eine Gefahr für die Quali­tät einer Pro­dukt­doku­men­tation. Indivi­duell gestal­tete Seiten sind prak­tisch nicht prüf­bar. Es ist schwerer, die Bearbei­tung einer Seite an einen anderen Autor zu über­geben. Die Bau­steine bilden ein abge­stimmtes Kon­zept. Abweichungen gefähr­den die Konsis­tenz. Abgren­zung ist eine hilf­reiche Methode, um diesem Prob­lem zu begeg­nen.

Die Gol­dene Regel der Gärt­ner besagt, dass eine Infor­mation, für die es keinen Bau­stein in der Pro­dukt­doku­men­tation gibt, ganz auto­matisch zur Pro­jekt­doku­men­tation gehört — und damit anderen Regeln unter­liegt. Natür­lich mit allen Konse­quen­zen bezüg­lich Nach­haltig­keit und Quali­tät. Eine Heraus­forderung für einen Gärt­ner ist, Stärke zu zeigen. Stärke, Auto­ren auf die Ein­haltung der Regeln der Pro­dukt­doku­men­tation einzu­schwö­ren.

Der Gärt­ner ist ver­ant­wortlich für die Aus­wahl der Werk­zeuge und der tech­nischen Infra­struk­tur für das Wiki. Das ist sozu­sagen die Ent­wick­lungs­umge­bung für die die Auto­ren. Er ist Experte im Zusam­men­hang mit Doku­men­tation. Seine Auf­gaben sind die Formu­lierung und Durch­setzung von Doku­men­tations­richt­linien, ähn­lich den Pro­gram­mier­richt­linien der Ent­wick­ler. Er sorgt für die Ein­hal­tung der Regeln der Methode cards+, ver­gleich­bar dem Scrum-Master als Hüter des Scrum-Pro­zesses oder einem IT-Experten für den Archi­tektur­stil. Aus dieser Argu­men­tation heraus ergibt sich zwangs­läufig, dass für die Pflege einer Pro­dukt­doku­men­tation ein Gärtner in der Art eines IT-Experten für Doku­men­tation gebraucht wird.

Der Gärt­ner ist Trainer für die Methode cards+. Er ist greif­bar für Auto­ren und Leser und hilft bei der Bewälti­gung von all­täg­lichen wie auch spezi­ellen Prob­lemen im Zusam­men­hang mit der Doku­men­tation. Ähn­lich wie beim Ver­hältnis von IT-Experte und Ent­wick­ler (Stich­wort Elfen­bein­turm­archi­tekt) ist es für einen Gärt­ner sehr hilf­reich, selbst auch Autor zu sein. Zumin­dest muss er akti­ver Leser sein.

Robert Bruckbauer beant­wor­tet Fra­gen und unter­stützt als Gärt­ner.


Methode

Schutz vor Wissens­verfall

Eine große Gefahr für die Leis­tungs­fähig­keit eines Teams sind Kopf­mono­pole und Wissens­inseln. Eine Per­son sammelt über lange Zeit wert­volles Wissen über das Pro­dukt. Er nutzt dieses Wissen, um erfolg­reich seine Auf­gaben im Team zu erfül­len. Dann ver­lässt er das Team. Wich­tiges, nicht schrift­lich erfass­tes Wissen geht unwider­bring­lich ver­loren. Selbst bei einem gut vor­berei­teten Aus­stieg mit Über­gabe oder einer schrift­lichen Nach­doku­men­tation gehen Infor­mationen ver­loren.

Ein Grund für Wissens­verfall ist die Träg­heit des mensch­lichen Gehirns und das damit ver­bun­dene Ver­gessen von Infor­mationen.

Ein Mensch erinnert sich gut an die aktu­ellen Auf­gaben. Aber an alle länger zurück­liegen­den, in der Regel abge­schlos­sene Auf­gaben kann er sich weni­ger gut erinnern. Wich­tige Details blei­ben uner­wähnt.

Die Ver­gemein­schaf­tung von Wissen (engl. shared knowledge) ist eine Maß­nahme, die diesem Ver­fall ent­gegen­wirkt. Jeder im Team teilt sofort sein Wissen. Er tut dies nach­haltig, also schrift­lich. Mit cards+ ist das Erfas­sen sehr ein­fach. Durch das Wiki gibt es keine Hür­den. Inter­net und ein Brow­ser reicht.


Methode

Fach­liche Schul­den

Das Mani­fest für agile Soft­ware-Ent­wick­lung ver­langt nicht den Ver­zicht auf Doku­mentation, sondern will, dass das eigent­liche Ziel, ein funktio­nieren­des Pro­dukt, nicht darun­ter lei­det. Doku­mentieren im All­gemei­nen wird trot­zdem von so man­chem Ent­wick­ler als Auf­gabe abge­lehnt. Sie wollen nur das doku­men­tieren, was für ihre Arbeit als Ent­wickler oder Tester einen Wert dar­stellt. Doku­men­tieren wird in beson­deren Situa­tionen gerne auch auf später ver­scho­ben. Andere Ent­wick­ler doku­men­tieren in der “heißen” Phase der Reali­sierung sehr gerne und aus­gie­big ihre aktu­elle Lösung. Es ent­stehen sehr genaue Beschrei­bungen und detail­getreue Bil­der. Sobald aber die Soft­ware eine gewisse Reife erreicht, sinkt die Moti­vation, diese Doku­mente zu aktuali­seren.

Beide Vor­gehens­weisen füh­ren zu fach­lichen Schul­den. Das Pro­dukt ist unvoll­stän­dig. Die Pro­dukt­doku­men­tation ent­hält sprich­wört­lich “ver­dor­bene” Doku­mente. Leider können Leser die “faulen” Stellen in der Doku­men­tation nicht immer erken­nen. Sie werden in die Irre geführt und ver­lieren das Ver­trauen in die Doku­men­tation. Damit beginnt ein Teu­fels­kreis. Weni­ger Leser bedeu­tet weni­ger Feed­back für die Auto­ren. Fehlen­des Feed­back führt zu sinkender Quali­tät. Sinkende Quali­tät ver­treibt weitere Leser.


Methode

Spezifi­kation ist Team­auf­gabe

Mit cards+ wird mit den Begriffen System­beschrei­bung, System­struktur, Spezifi­kation und Test­plan eine klare Auf­gaben­teilung zwischen Pro­dukt­verant­wort­lichen und seinem Team ange­strebt.

Der Produkt­verant­wort­liche bewegt sich im Wiki. Er nutzt die Bau­steine der System­beschrei­bung, um seine Vision bis hinunter zu einer kon­kreten Fähig­keit der Soft­ware zu doku­men­tieren. Er nutzt die Bau­steine der System­struk­tur, um Diensten und Objekten in Abstimmung mit dem Team ein­deutige Namen und einen fach­lichen Zweck zu geben. Für jede gefor­derte Fähig­keit schreibt er einen Arbeits­auf­trag (engl. story) für die Ent­wickler. Dort konkre­tisiert er einen unvoll­ständigen Bau­stein Case durch Akzep­tanz­kri­terien. Unvoll­ständig heißt in diesem Fall ohne Lösung.

Das Team nimmt ent­sprechend der Priori­sierung des Pro­dukt­verant­wort­lichen einen Arbeits­auf­trag an. Es ist voll­kommen unstrit­tig, dass Pro­gram­mieren und Testen beides Auf­gaben des Teams sind. Sie suchen eine Lösung für die gefor­derte Fähig­keit der Soft­ware im Rahmen des gewähl­ten Archi­tektur­stils. Die Akzep­tanz­kri­terien im Arbeits­auf­trag sind Grund­lage für die Test­pläne. Die Ergeb­nisse des agilen Ent­wick­lungs­pro­zesses, also Code, code-nahe Arte­fakte, Test­pläne und Spezifi­kationen, werden in einer quell­text-basier­ten Ver­sions­ver­wal­tung nach­voll­zieh­bar gespei­chert.

In der Methodik von cards+ erge­ben die Bau­steine im Wiki als auch die Ergeb­nis­doku­mente der Ent­wickler und Tester zusam­men eine voll­stän­dige Pro­dukt­doku­men­tation. Eine Doku­men­tation wirkt aber nur dann voll­stän­dig, wenn alle doku­men­tier­ten Infor­mationen in einem Medium präsen­tiert wird. Das ist im Fall von cards+ das Wiki. Dort befin­den sich bereits die Bau­steine. Durch geeig­nete Konver­tierung werden Spezifi­kationen der Ent­wickler und Test­pläne der Tester im Wiki ver­öffent­licht.