Agil dokumentieren

Mit cards+ wird inkrementelles Doku­men­tieren in einem agilen Software-Entwicklungsprozess zur leist­baren Auf­gabe. Die Doku­men­te werden prüf­bar, die Quali­tät mess­bar.

cards+ ist prak­tisch,
weil wir[1] …

… implizi­tes Wissen expli­zit machen.

Wissen ist ein sehr wert­volles Gut. Wissen steckt aber erst ein­mal in den Köpfen der beteilig­ten Per­sonen. Es ist impli­zit. Lesbar program­miert und ange­messen kommen­tiert kann Code mit den Bau­steinen Domain, Service, Entity, Event und Layout als expli­zites Wissen im Wiki ver­öffent­licht werden. Ein Pro­dukt­verant­wort­licher hat fun­dierte Kennt­nisse über den Ein­satz der Soft­ware. Er kennt die Ziele, die der Auftrag­geber mit der Soft­ware ver­folgt. Er weiß sehr genau, »wer« »wann« »welche« Fähig­keit der Soft­ware ein­setzt. Mit den Bau­steinen Topic, Epic und Case kann er dieses Wissen mit dem Team teilen.

… alle Doku­men­te prüf­en kön­nen.

Prüf­bar­keit ist ein wich­tiges Quali­täts­merk­mal einer guten Pro­dukt­doku­men­tation. Durch die klare Struk­tur im Wiki und den Regeln für Inhalt und Form der Bau­steine von cards+ haben Autoren ein Gerüst, an dem sie sich beim Schrei­ben orien­tie­ren kön­nen. Mit der Durch­führung eines Reviews wird eine Seite for­mal und inhalt­lich von ande­ren Autoren hin­sicht­lich dieses Gerüs­tes über­prüft. Diese ziel­gerich­tete Quali­täts­prüfung ist eine plan­bare Auf­gabe in einem agi­len Ent­wick­lungs­pro­zess. Ergänzend dazu prüft jeder Leser beim Lesen der Sei­ten neben der Rich­tig­keit auch die Ver­ständ­lich­keit der Inhalte. Mit der Kommen­tar­funk­tion im Wiki kann er dem Autor einer Seite nach­voll­zieh­bares Feed­back geben. Jeder­zeit.

… die Doku­men­tation voll­stän­dig ist.

Voll­ständig­keit ist ein weiteres wichtiges Quali­täts­merk­mal einer guten Pro­dukt­doku­men­tation. Die Bau­steine Topic, Epic und Case reichen, um alle Fähig­keiten der Soft­ware als System­beschrei­bung voll­ständig und prüf­bar zu doku­men­tie­ren. Die Bau­steine Domain, Service, Entity, Event und Layout beschrei­ben die System­struk­tur des IT-Systems voll­ständig und prüf­bar. Der Bau­stein Decision reicht, um den Archi­tektur­ent­wurf nach­voll­zieh­bar als Samm­lung aller für das IT-System rele­van­ter Ent­schei­dungen mit Begrün­dung zu erfas­sen. Mit dem Bau­stein Spec werden die Kon­sequen­zen der Ent­scheidun­gen doku­men­tiert.

… ange­messen Doku­men­tie­ren ler­nen.

Ange­messen­heit ist ein Ziel, für das es keine ein­deuti­gen Regeln gibt. Trotz­dem ist es ein wich­tiges Ziel, weil nur so Doku­men­tie­ren zu einer leist­baren Auf­gabe wird. Der vor­gegebe­ne Auf­bau der Bau­steine hilft den Autoren, das rich­tige Maß für den Umfang der Doku­mente zu fin­den. Viele bekannte Prak­tiken und Prinzi­pien der Ent­wick­ler sind leicht auf die Arbeit im Wiki über­trag­bar. Mit Prin­zipien wie KISS, DRY oder INVEST ver­fol­gen Autoren beim Doku­men­tie­ren die gleichen Ziele wie Ent­wick­ler beim Pro­grammie­ren. Ein Doku­ment ist ange­messen, wenn ein Leser den Inhalt ver­steht und für seine eigene Arbeit ver­wen­den kann. Bei der gemein­samen Arbeit im Wiki bekommen die Autoren durch Feed­back der Leser die not­wendi­gen Impulse zur konti­nuier­lichen Ver­besserung der Pro­dukt­doku­men­tation.

… uns besser ver­ste­hen.

Inter­essierte Par­teien und die gesamte Pro­jekt­organi­sation finden schell eine gemein­same Sprache. Das ist ein Erfolgs­fak­tor für die Quali­tät der Ergeb­nisse eines agi­len Ent­wick­lungs­pro­zesses. Durch das Glossar und die Bau­steine der System­struk­tur werden wich­tige Begriffe ein­deutig defi­niert und aus­reichend gut erklärt. Das Wiki ver­schafft sowohl Lesern als auch Autoren einen Über­blick über das Pro­dukt und för­dert ein gemein­sames Ver­ständ­nis für Prob­leme und Lösun­gen.

… echten Wert für alle schaf­fen.

Eine Pro­dukt­doku­men­tation hat einen Wert für alle inter­essierten Par­teien und die gesamte Pro­jekt­organi­sation. Sie wird auf­grund ihrer Quali­tät wert­ge­schätzt. Von allen. Autoren stre­ben eine voll­stän­dige und rich­tige Doku­men­tation an. Das gelingt nur, wenn die Doku­mente prüf­bar sind. Die Doku­men­tation muss schlüs­sig sein, ihre Inhalte dür­fen sich nicht wider­sprechen. Jedes Wissen wird am besten nur einmal erfasst. Dazu werden Teile vom Code, Spezifi­katio­nen und Test­pläne durch Ver­öffent­lichung im Wiki für alle les­bar.

… Doku­mente schritt­weise ent­wickeln.

Eine 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 prozessorientierten 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 die Soft­ware ent­­wickelt wird. cards+ erwei­tert die Gren­zen der Pro­dukt­doku­men­tation. Im Wiki wird nichts doku­men­tiert, was Ent­wick­ler bereits ange­messen mit les­baren Tei­len vom Code spezifi­zieren oder Tester bereits ange­messen mit Test­plänen in einer Test­pyra­mide beschrei­ben. Mit jedem neuen Pro­dukt­inkre­ment gibt es neue doku­men­tierte Infor­matio­nen, die im Wiki ver­öffent­licht werden.

… auf dauer­haft hohe Quali­tät ach­ten.

Eine Pro­dukt­doku­men­tation wird über die gesamte Lebens­zeit eines Pro­duk­tes benö­tigt. Durch Ver­änderun­gen im Pro­jekt­umfeld oder in der Pro­jekt­organi­sation geht regel­mäßig Wissen ver­loren, wenn es nicht doku­men­tiert wurde. cards+ ist ein pro­zess­orien­tier­ter Ansatz für die Erfassung von Wissen mit einem hohen Anspruch an die Quali­tät der Ergeb­nisse. Autoren erfassen Wissen, wann es ent­steht. Sie erar­beiten es zusam­men mit den inter­essierten Par­teien und Domänen­exper­ten. Dabei unter­stützen sie sich gegen­seitig und ler­nen von­ein­ander. Sie set­zen das simple Prinzip der Pfad­finder­regel für die Steige­rung der Quali­tät der doku­men­tier­ten Infor­matio­nen ein. Ein »sauberes« Doku­ment ist ent­sprechend den Vor­gaben des Bau­steins voll­stän­dig und hat keine offen­sicht­lichen Feh­ler oder Lücken.


[1] Mit »wir« sind dabei alle am Pro­dukt beteilig­ten Per­sonen gemeint, also inter­essierte Par­teien, Pro­dukt­verant­wort­liche und die gesamte Pro­jekt­organi­sation.