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.

Die Digi­tale Trans­for­mation braucht Wissens­manage­ment.

Unter­nehmen brau­chen das Wissen ihrer Be­schäf­tig­ten. Wissen muss be­wahrt und ge­teilt wer­den. Wissens­inseln sind ein Risi­ko in jeder Orga­nisation. Viel Wissen steckt auch in Soft­ware. Agile Soft­ware-Ent­wick­lung ist darum Teil der digi­talen Trans­for­mation in vielen Unter­neh­men. Dabei kommt es aber nicht nur darauf an, agil vor­zu­gehen, son­dern gene­rell flexi­bel zu sein. Agili­tät wird häu­fig in einem Atem­zug mit Ge­schwin­dig­keit oder Effi­zienz ge­nannt. Aber über Doku­men­tation wird nicht so häu­fig ge­spro­chen. Es gibt die einen, die auf Doku­men­tation ver­zich­ten wollen. »Code und Test­pläne reichen!« sagen sie. Andere wollen wiede­rum alles ganz genau auf­schrei­ben. »Wissen darf nicht ver­loren gehen!« for­dern sie.

In diesem Span­nungs­­­­feld bewegt sich cards+. Eine agile Orga­nisation schätzt funktio­nierende Soft­ware. Lang­fristig betrach­tet braucht sie auch eine ange­messene Doku­men­tation für die Soft­ware. Mit cards+ sind beide Ziele von Anfang an erreich­bar. Soft­ware und Doku­men­tation wird Hand in Hand inkre­men­tell ent­wickelt. Das Wiki ist das Repository für die doku­men­tier­te Infor­matio­nen aller Art.

Doku­men­tie­ren erfor­dert wie Pro­gram­mie­ren viel Krea­tivi­tät und hand­werk­liches Ge­schick. Ein­fache Regeln und klare Struk­turen stei­gern so­wohl die Quali­tät der Er­geb­nisse als auch Pro­duk­tivi­tät ihres Teams. Der Gärt­ner ist als Coach für Auto­ren und Le­ser immer greif­bar und hilft bei der Be­wälti­gung von all­täg­lichen wie auch spe­ziel­len Prob­lemen im Zu­sam­men­hang mit der Doku­men­tation.

Mehr erfahren

Konti­nuier­liche Ver­besserung ist eine weitere wich­tige Gemein­sam­keit beim Doku­men­tie­ren und Pro­gram­mie­ren. Viele bekannte Prin­zipien und Prak­tiken der Ent­wick­ler kön­nen Auto­ren im Wiki direkt (z.B. KISS, DRY oder INVEST) oder in nur leicht abge­wan­del­ter Form (z.B. COC oder SRP) an­wen­den. Ein Gärt­ner ist Ex­per­te im Zusam­men­hang mit Dok­umen­tation. Er sorgt für die For­mulie­rung und Durch­setzung von Doku­men­tations­richt­linien, ver­gleich­bar mit den Pro­gram­mier­richt­linien der Ent­wick­ler.

Mehr erfahren

Domain-Driven Design ist ihr favori­sier­ter Ansatz für die Analyse.

Sie nutzen Domain-Driven Design für strate­gisches und takt­isches Design in ihren Ent­wick­lungs­pro­jek­ten. Ihre Domänen­exper­ten stellen die Modellie­rung der Fach­lich­keit in den Vorder­grund und erschaf­fen eine domänen­spezi­fischen Sprache. Jeder kennt sie, jeder spricht sie, egal ob er oder sie als Ent­wickler, Tester oder Nutzer betei­ligt ist.

Trifft das zu, dann haben Sie opti­male Voraus­setzun­gen für einen erfolg­rei­chen Ein­satz von cards+ zur nach­haltigen Sicherung der Ergeb­nisse aus dem stra­tegi­schen und tak­ti­schen Design im Wiki. Nach­haltig bedeu­tet, dass das Design konti­nuier­lich mit dem Fort­schritt der Ent­wick­lung ange­passt wird. Mit dem Ein­satz von cards+ haben Sie ein leben­diges Design.

Mehr erfahren

Agile Soft­ware-Ent­wick­lung ist ge­lebte Reali­tät in ihren Pro­jek­ten.

Sie setzen auf Agilität in der Organi­sation ihrer Ent­wick­lung. Ihr An­satz ist empi­risch, inkre­men­tell und itera­tiv. Schritt für Schritt wird ihr Team besser und schneller. Selbst­organi­siert. Maxi­mal moti­viert. Ihr Fokus liegt auf Quali­tät und Exzel­lenz. In kur­zen Zyk­len ent­wickeln Sie kunden­wirk­same Inkre­mente.

Möchten Sie ihren Fort­schritt nach­haltig sicht­bar machen und jedes Inkr­ement ange­messen doku­mentie­ren, dann inte­grie­ren Sie cards+ in ihren Pro­zess und nutzen ein Wiki für ihre Doku­men­tation.

Mehr erfahren

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

Doku­mente agil und itera­­tiv ent­wickeln.

Mit dem Ein­satz von cards+ ist jede 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. Itera­tiv bedeu­tet fort­laufende Wieder­holung, ver­bun­den mit der Chance, sich Schritt für Schritt zu ver­bessern. 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.

Methode

Agil zu doku­men­tieren heißt bedarfs­­gerecht zu doku­men­tieren.

Prozesse

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

Das Wiki.
Ein Erfolgs­faktor.

Doku­mente inkre­­­­­men­­­­­tell ent­wickeln.

Jedes inkre­­­­­men­­­­­telle Vor­­­­­gehens­­­­­modell basiert auf der Idee der kleinen Schritte zur Reduk­tion der Kom­­­­­plexi­­­­­tät. Damit wird 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. Das Cynefin-Modell teilt Sys­teme in die fünf Kate­gorien “offen­sicht­lich”, “kompli­ziert”, “kom­plex”, “chao­tisch” und “un­klar” ein. In den Inkre­­­­­­men­ten kann jedes kom­­­­­­plexe Pro­­­­­b­lem in ein kom­­­­­­pli­zier­­­­­­tes, man­ch­­­­­mal sogar offen­­­­­­sicht­­­­­­liches Pro­­­­­­blem zer­legt wer­den. cards+ hilft dabei, in die­sem Bereich zu blei­ben.

Methode

Es ist ein­facher, einer Hand­voll kleinerer Heraus­forderun­gen zu bege­gnen als einer einzel­nen großen.

Struk­tur

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

Das Meta­modell.
Ein Überblick.

Doku­mente wie Quell­text ent­wickeln.

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 inkre­men­tell ent­wickelt und im Code-Reposi­tory ver­sio­niert gespei­chert wer­den. Damit kann ein großer Teil der Pro­dukt­doku­men­tation durch auto­matisier­bare Ver­öffent­lichung im Wiki direkt aus der Code-Basis in den Bau­steinen von cards+ inte­griert werden.

Methode

Soft­ware ist nichts ande­res als aus­führ­bares Wissen.

Quali­tät

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

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

Von den Anfän­gen bis heute.

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.

Ein Fachartikel mit dem Titel «Agile Dokumentation für Stakeholder und Projektmitarbeiter» im Online-Magazin ist die erste umfassende Veröffentlichung der Methode cards+.

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.

Das Fachmagazin hat in der Ausgabe 02/2020 den Schwerpunkt Domain-Driven Design. Der Beitrag mit dem Titel «Vom Problemraum zur Lösung» zeigt die Vorteile der Kombination von Domain-Driven Design und cards+.

Bis heute ist cards+ Teil der Quali­täts­poli­tik der Firma e.mundo.

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 im sozia­len Netz­werk LinkedIn tun.

Feedback geben