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.


Wissens­­­­­manage­ment

Ein­fach und prak­tisch

cards+ ist eine Methode zum Erstel­len und Pfle­gen einer Pro­dukt­doku­men­tation für Soft­ware in einem Wiki. Das geht ein­­fach. Doku­men­tie­ren ist wie Pro­gram­mie­ren ein krea­tiver Pro­zess, aber auch ein Hand­werk. Viele Prin­zipien und Prak­tiken der Ent­wickler können Autoren im Wiki direkt oder in nur leicht abge­wandel­ter Form anwen­den. Das ist sehr prak­­tisch.

Ein Wiki ist ein­fach zu bedie­nen. Autoren ver­wen­den vor­defi­nierte Bau­steine in einer fes­ten Struk­tur. Sie ver­mei­den Auf­wand für die Erstel­lung und Pflege von Doku­men­tation im Wiki, indem sie les­bare Teile vom Code, Spezi­fikatio­nen der Ent­wick­ler und Test­pläne der Tes­ter im Wiki ver­öffent­lichen. Inter­essierte Par­teien, Pro­dukt­verant­wort­liche und die gesamte Pro­jekt­organi­sation unter­stüt­zen sich gegen­sei­tig. Sie nut­zen Reviews für die Siche­rung der Quali­tät der Ergeb­nisse agi­ler Soft­ware-Ent­wick­lung. Dokumen­tation ist auch ein Ergeb­nis. Sie ler­nen von­einan­der. Lau­fend. Sie fin­den eine gemein­same Sprache. Sie können sich jeder­zeit im Wiki über das Pro­dukt infor­mie­ren, wie es jetzt ist. Sie geben Feed­back. Kon­tinuier­lich. Sie nutzen das Feed­back zur Ver­besserung der Soft­ware. Ganz ein­fach.

Pro­gram­mie­ren ist eine krea­tive Tätig­keit, mit dem Ziel, Wissen in Soft­ware zu über­set­zen. Die Devise lau­tet: Pro­gram­mie­ren ist doku­men­tie­ren. Autoren der Pro­dukt­doku­men­tation im Wiki setzen bewährte Prin­zipien und Prak­tiken der Ent­wick­ler ein. Sie ent­wickeln Doku­mente schritt­weise, weil die Bau­steine klar defi­niert und auf­einan­der auf­bauend sind. Sie erstellen Inhalte in hoher Quali­tät, weil sie prüf­bar sind. Der Pro­dukt­verant­wort­liche erklärt in der System­beschrei­bung, »wer« »wann« »welche« Fähig­keit der Soft­ware braucht. Die Frage, »wie« die Soft­ware funktio­niert, beant­wor­tet das Team in jedem Pro­dukt­inkre­ment mit Spezifi­katio­nen und Test­plänen — durch Ver­öffent­lichung. Diese Prin­zipien und ihre prak­tische Umset­zung mit cards+ sind Erfolgs­fakto­ren agi­ler Soft­ware-Ent­wick­lung.

Der Reise-Butler.
Ein Fall­bei­spiel.


Wissens­­­­­manage­ment

Agil und itera­­tiv

Mit dem Ein­satz von cards+ ist eine agile Pro­jekt­organi­sation in der Lage, ziel­gerich­tet und itera­tiv eine Pro­dukt­doku­men­tation zu ent­wickeln. Ziel­gerich­tet bedeu­tet, dass die erstell­ten Doku­mente einen Wert für die Organi­sation haben. Mit dem Fort­schritt in der Ent­wick­lung der Soft­ware wächst auch die Pro­dukt­doku­men­tation, als inte­gra­ler Bestand­teil des Pro­dukt­inkre­men­tes. Doku­men­tieren wird zur leist­baren Auf­gabe des gesam­ten Teams. Die Doku­men­tation wird prüf­bar, die Quali­tät mess­bar.

Doku­men­tieren bleibt trotz­dem ein Reiz­wort. Es gibt die einen, die auf Doku­men­tation ver­zich­ten wollen. »Code und Test­pläne reichen!«, sagen sie. Andere wollen wieder­rum alles ganz genau auf­schrei­ben. »Das Wissen darf nicht ver­loren gehen!«, for­dern sie. In diesem Span­nungs­­­­feld bewegt sich cards+.

Methode

Agil Doku­men­tieren heißt bedarfs­­gerecht Doku­men­tieren.

Prozesse

Tue es oder tue es nicht. Es gibt kein Ver­suchen.

Quali­tät

Quali­tät ist das Ergeb­nis einer Viel­zahl selbst­loser Akte der Sorg­falt.

Struk­tur

Das Prob­lem zu erken­nen, ist wich­tiger, als die Lösung zu erken­nen.

Das Wiki.
Ein Erfolgs­faktor.


Wissens­­­­­manage­ment

Inkre­­­­­men­­­­­tell

Jedes inkre­­­­­men­­­­­telle Vor­­­­­gehens­­­­­modell basiert auf der Idee der kleinen Schritte zur Reduktion der Kom­­­­­plexi­­­­­tät. In den Inkre­­­­­menten redu­­­­­zieren wir jedes kom­­­­­plexe Pro­­­­­blem in ein kom­­­­­plizier­­­­­tes, manch­­­­­mal sogar offen­­­­­sicht­­­­­liches Pro­­­­­blem. Damit machen wir ein kom­­­­­plexes Pro­­­­­blem be­­­­­herrsch­­­­­bar. Als agile Methode profi­­­­­tiert cards+ von den Erkennt­­­­­nissen aus der inkre­­­­­men­­­­­tellen Ent­­­­­wick­­­­­lung und nutzt die Vor­­­­­teile konti­­­­­nuier­­­­­licher Ver­­­­­besserung für die Doku­men­tation.

Ascii­doc ist eine leicht­­gewich­t­ige Aus­­zeich­nungs­­sprache für eine text­­basierte Doku­­menten­­generie­rung. Eine Ascii­doc-Datei kann u.a. in die For­­mate HTML5, EPUB3 und PDF umge­wan­delt werden. Eine Preview für Ascii­doc-Dateien ist als Zusatz prak­tisch in jeder IDE ver­füg­bar.

Eine Ascii­doc-Datei kann wie Quell­­text ent­wickelt und versio­­niert werden. Damit kann ein großer Teil der Pro­dukt­doku­men­tation wie Code inkre­men­tell ent­wickelt und im Wiki inte­griert in den Bau­steinen von cards+ ver­öffent­licht werden.

Asciidoc(tor).
Für Qualität.


Wissens­­­­­manage­ment

Referen­zen

Ein im Jahr 2014 gestar­tetes agiles Ent­wick­lungs­pro­jekt hatte das Ziel, das IT-System der Trans­port­leitungen der Deutschen Bahn zu moderni­sieren. Die dort gewon­nenen Erkennt­nisse führ­ten zum ersten Ent­wurf von cards+ als Ansatz für inkre­men­telles Doku­men­tieren.

Die Deutsche Bahn nutzt cards+ seit 2016 als Vor­lage für einen pro­jekt­­spezi­fischen An­satz für inkre­men­telles Doku­men­tieren im agilen Ent­wick­lungs­pro­zess für ein neues IT-System zur Reisen­den­infor­mation.

Sortimo Inter­natio­nal GmbH hat ihr Pro­dukt­portfolio in 2018 erwei­tert und geht mit dem Bekle­bungs­konfi­gura­tor in den Markt. Für die Doku­men­tation der Pro­jekt­ergeb­nisse wurde cards+ als Ergän­zung zum agilen Ent­wick­lungs­pro­zess gewählt.

Auf­grund der Vor­gaben der DS-GVO möchte ich als Ver­ant­wort­licher für den Inhalt keine Kommen­tar­funk­tion anbie­ten. Wer Fra­gen hat oder ein­fach nur Feed­back zu cards+ geben möchte, kann das sehr gerne in der moderier­ten Gruppe Agil doku­men­tie­ren im sozia­len Netz­werk Xing tun.

Feedback geben