Methode

Doku­men­tation betrifft jeden

Die Betroffen­heit einer Person von einer Sache lässt sich sehr schön durch die Fabel vom Huhn (engl. chicken) und vom Schwein (engl. pig) erklä­ren. Eine Par­tei ist betei­ligt (engl. committed), die andere inter­essiert (engl. involved).

The Chicken says: » Hey Pig, I was thin­king we should open a restau­rant! «
Pig replies: » Hm, maybe, what would we call it? «
The Chicken responds: » How about ‘ham-n-eggs’? «
The Pig thinks for a moment and says: » No thanks. I’d be commit­ted, but you’d only be involved. «

Wikipedia

Beteiligt sein bedeutet, von einer Sache über­zeugt zu sein, sich persön­lich dafür einzu­setzen, etwas zu tun. Inter­essiert sein hin­gegen bedeutet, sich ledig­lich mit einer Sache zu befassen. Agile Soft­ware-Ent­wick­lung ver­stärkt die Bedeu­tung beteilig­ter Per­sonen und schützt sie vor dem nega­tiven Ein­fluß inter­essierter Par­teien. Feed­back zum Pro­dukt will ein Pro­dukt­verant­wort­liche aber von allen Ziel­gruppen, ohne Ein­schränkung und immer wert­schätzend.

Die Ziel­grup­pen der Pro­dukt­doku­mentation sind ganz all­gemein inter­essierte Par­teien sowie die Pro­jekt- und Betriebs­organi­sation. Für das Gelingen einer Pro­dukt­doku­men­tation muss der Pro­dukt­verant­wort­liche es schaffen, das sich alle Ziel­grup­pen (oder deren Ver­tre­ter) mindes­tens als Leser beteili­gen. cards+ unter­stützt ihn bei diesem Ver­such.


Defi­nition

Welche Quali­täts­merk­male hat ein Baustein?

Rich­tig­keit

Ein Bau­stein der Pro­dukt­doku­men­tation ist rich­tig, wenn er einen Teil des Pro­dukt­wissens kor­rekt erfasst. Das Glossar bildet die Grund­lage für das Voka­bular des Pro­duktes und hilft bei der Durch­setzung der gemein­samen Sprache. Ein Text mit Begriffen aus dem Glossar, richtig ver­wen­det, ist daher korrekt, wenn wir davon aus­gehen, dass die Ein­träge Im Glossar korrekt sind. Die Ver­knüp­fung von Begriffen im Text mit Ein­trägen im Glossar gibt dem Autor die Sicherheit, dass er den richtigen Begriff gewählt hat. Sprach­liche Richtig­keit (Ortho­gra­phie, Gram­matik, Aus­druck) der Texte wird grund­sätz­lich voraus­gesetzt.

Voll­stän­dig­keit

Ein Bau­stein der Pro­dukt­doku­men­tation ist voll­stän­dig, wenn er mit der rich­tigen Sei­ten­vor­lage erstellt und alle Abschnitte kor­rekt mit Inhalt gefüllt wurden. Es ist nicht zuläs­sig, dass ein Autor Abschnitte aus dem Bau­stein zu ent­fernt. Der Bau­stein wäre un­voll­stän­dig, der Grund wäre für einen Leser nicht erkenn­bar. Tritt der Fall ein, dass ein Autor einen Abschnitt in einem Bau­stein nicht sinn­voll aus­füllen kann, dann wird genau dieser Umstand mit einem Leer­ver­merk doku­mentiert. Leer­ver­merke wie “Keine Angabe” oder “Nicht zutref­fend” machen einen Bau­stein voll­stän­dig, und in der Konse­quenz auf Voll­stän­dig­keit prüf­bar.

Über­sicht­lich­keit

Eine klare, über­sicht­liche Dar­stel­lung der Inhalte trägt wesent­lich zur Akzep­tanz der Pro­dukt­doku­mentation bei. Der Aufbau der Bau­steine soll Autoren in ihrer Arbeit unter­stüt­zen. Die Bau­steine der System­beschrei­bung sind streng hierar­chisch aufge­baut und auf maximal zwei Über­schrif­ten­ebenen beschränkt. In den Bau­steinen der System­struk­tur gibt es immer einen Steck­brief als Ein­stieg und den Abschnitt Spezifi­kation als Abschluss.

Ver­ständ­lich­keit

Ein Bau­stein der Pro­dukt­doku­men­tation ist ver­ständ­lich, wenn er in der Sprache der Ziel­gruppen geschrie­ben ist. Der Text in einem Bau­stein muss nicht durch Wort­reich­tum glän­zen. In kurzen Sät­zen vermit­telt der Autor sein Pro­dukt­wissen. Die Ver­knüp­fung von Begriffen im Text mit Ein­trägen im Glossar för­dert das Ver­ständ­nis für den Leser. Gleich­zeitig ist es eine Maß­nahme für den Autor, den Text kom­pakt zu hal­ten. Ein gut gepfleg­tes Glossar dient hier als Mini-Lexi­kon des Pro­duktes.


Feed­back

Rück­meldung an den Pro­dukt­verant­wort­lichen

Soft­ware-Ent­wick­lung ist ganz abstrakt formu­liert die Trans­for­mation von Wissen in Code. Die Bau­steine Topic, Epic und die Ausgangs­lage im Bau­stein Case kann der Pro­dukt­verant­wort­liche bereits im Back­log-Manage­ment nut­zen, um Wissen nach­hal­tig zu erfassen. Ein Team braucht sehr detail­rei­ches Wissen, um eine gefor­derte Fähig­keit der Soft­ware kor­rekt und voll­stän­dig zu ver­ste­hen. Dieser Bedarf geht darü­ber hinaus, was nach dem Prin­zip KISS sinn­voll in den Bau­steinen erfasst werden kann. Der Pro­dukt­verant­wort­liche nutzt darum eine Story, um diese Wissens­lücke am Beginn der Itera­tion zu schlie­ßen.

Eine Story im Back­log ist — ganz banal gespro­chen — das Ver­spre­chen, mit­einan­der zu reden.

Die Story verknüpft er mit dem Bau­stein Case. Mit dem Akzep­tanz­krite­rien in der Story formu­liert er seine Erwar­tung an die Lösung. Er beant­wor­tet die Fra­gen der Ent­wick­ler. Gleich­zei­tig sind diese Fra­gen auch Hin­weise, wo ggfs. die Texte in den Bau­steinen ver­bessert werden soll­ten.

Cynefin offers five decision-making contexts: simple, complicated, complex, chaotic, and disorder. The domains offer a sense of place from which to analyse behaviour and make decisions. Cynefin is a Welsh word for habitat.

David John Snowden

Im nächsten Schritt prüft das Team die Story hin­sicht­lich Voll­ständig­keit und schätzt die Kom­plexi­tät. In der Ana­lyse der Story (engl. refinement) redu­ziert das Team jede kom­plexe Auf­gabe in eine Reihe kompli­zier­ter, manch­mal sogar offen­sicht­licher Teil­auf­gaben. Eine offen­sicht­liche Teil­auf­gabe hat eine wieder­kehrende Lösung. Für eine kompli­zierte Teil­auf­gabe muss das Team wenigs­tens eine schätz­bare Lösungs­idee ent­wer­fen. Damit wird eine komp­lexe Auf­gabe beherrsch­bar.

Jetzt liegt es am Team, für die gefor­derte Fähig­keit, wie sie im Bau­stein Case in der Aus­gangs­lage beschrie­ben wird, eine passende Lösung in der Soft­ware zu finden. Die Ergeb­nisse des agilen Ent­wick­lungs­pro­zesses kata­logi­sieren sie mit den Bau­steinen der System­struk­tur und aktuali­sie­ren die Spezifi­kationen in den Bau­steinen Service und Event bzw. Entity. Auf dem Weg der Lösungs­fin­dung für eine kom­plexe Auf­gabe treffen sie ggfs. noch tech­nische Ent­schei­dungen, die sie mit dem Bau­stein Decision begrün­den und erar­bei­ten Reali­sierungs­kon­zepte, die sie mit dem Bau­stein Spec beschrei­ben. Als Abschluss ergänzen sie die Essenz­schritte im Bau­stein Case mit Bezug auf die Bau­steine der System­struk­tur. Die Tester erwei­tern ihre Test­fälle in der Test­pyra­mide zum Nach­weis für die Erfül­lung der Akzep­tanz­krite­rien in der Story.

An diesem Punkt — in der Regel am Ende der Ite­ration — schließt sich der Kreis. Das Pro­dukt­inkre­ment ist fer­tig. Der Pro­dukt­verant­wort­liche kann nun selbst prüfen, ob seine Erwar­tun­gen, die er in der Story formu­liert hat, durch die Lösung vom Team erfüllt wur­den. Das bedeu­tet bezo­gen auf die Pro­dukt­doku­men­tation, dass in min­des­tens einem Bau­stein Service die im Wiki ver­öffent­lichte Spezifi­kation geän­dert wurde. Sie ent­hält nun die für die Reali­sierung der neuen Fähig­keit ergänz­ten oder geänder­ten Geschäfts­regeln oder Algo­rith­men. Haben sich Daten­struk­turen geändert, dann gibt es Änderungen in den Spezifi­kationen der Bau­steine Event bzw. Entity. Die ver­öffent­lichten Test­pläne ent­hal­ten zusätz­liche Test­fälle, passend zu den Akzep­tanz­krite­rien in der Story.

Kurz gesagt hat der Pro­dukt­verant­wort­liche die Mög­lich­keit, die Ergeb­nisse aus dem agi­len Ent­wick­lungs­pro­zess direkt im Wiki nach­zule­sen. Das Team muss dafür nur daran den­ken, die klei­nen Korrek­turen an den Spezifi­kationen gleich­zeitig mit den Änderungen am Code und den Test­plänen zu machen. Die Ver­öffent­lichung im Wiki läßt sich auto­mati­sie­ren. Der Aus­löser ist die Frei­gabe des Pro­dukt­inkre­ments. Sie tun das aber nicht für den Pro­dukt­verant­wort­lichen. Sie profi­tie­ren selbst davon. Das kann man ohne Ein­schrän­kung als Win-Win-Situa­tion bezeich­nen.

Ein­führung in das Back­log-Manage­ment in 45 Minu­ten.


Feed­back

Schnitt­stel­len­beschrei­bung für Part­ner­sys­teme

Schnitt­stellen­beschrei­bungen sind alter­nativ­los in einer kom­plexen IT-System­land­schaft mit vielen unab­hängi­gen Par­tner­systemen aus ver­schiede­nen Organi­sationen eines Unter­nehmens. Ein Pro­dukt­verant­wort­licher darf sich trotz­dem die Frage stel­len, wie umfang­reich so ein Doku­ment sein muss. Mit cards+ ist es mög­lich, eine Schnitt­stellen­beschrei­bung aus einem Rahmen­doku­ment — die Start­seite der Schnitt­stelle — und den Bau­steinen der System­beschrei­bung und System­struk­tur zusam­men­zu­stel­len. Neben der Start­seite muss der Pro­dukt­verant­wort­liche nur eine weitere Seite je ange­schlos­senem IT-System im Wiki anle­gen. Die Start­seite legt mit ihrem Seiten­titel eine ein­deutige Kennung für die Schnitt­stelle fest, auf die auch in anderen Doku­men­ten referen­ziert werden kann. Sie ist prak­tisch eine Link­samm­lung für alle Bau­steine, die rele­vant für die Schnitt­stelle sind. Die Rele­vanz wird eben­falls durch die Kennung der Schnitt­stelle als Stich­wort in den betroffe­nen Seiten aus­gedrückt.

Die Start­seite hat fol­gen­den grund­sätz­lichen Auf­bau:

  • Im Abschnitt Referen­zen werden alle ange­schlos­senen IT-Systeme gelistet.
  • Der Abschnitt System­kontext zeigt die End­punkte (Service) der beteilig­ten IT-Systeme in einem schema­tischen Kompo­nenten­über­blick.
  • Im Abschnitt Operatio­nen wird jede ein­zelne Operation der Schnitt­stelle beschrie­ben. Neben einer kur­zen Beschrei­bung der Operation gibt es hier Infor­matio­nen zur Häufig­keit der Auf­rufe, zu den Para­metern und Rück­gabe­wer­ten und Beson­der­hei­ten der Feh­ler­behand­lung.
  • Der Abschnitt Beschrei­bung ver­knüpft in einer Tabelle jede Operation mit den Fähig­keiten der Soft­ware (Case) und einem Aus­löser (Event) — falls es einen gibt.
  • Der Abschnitt Versio­nierung legt eine ver­bind­liche Stra­tegie für die Evo­lution der Schnitt­stelle fest, mit einer Ver­knüpfung zum ent­sprechen­den Kon­zept (Spec).
  • Der Abschnitt Quali­täts­merk­male legt ver­bindl­iche Vor­gaben für den Betrieb der Schnitt­stelle fest, mit Ver­knüpfun­gen zu ent­sprechen­den Kon­zep­ten (Spec) und Ent­schei­dungen (Decision)

Der Pro­dukt­verant­wort­liche erreicht durch dieses Vor­gehen ein hohes Maß an Wieder­ver­wen­dung bereits exis­tieren­der doku­men­tier­ter Infor­matio­nen im Wiki.

  • Der End­punkt der Schnitt­stelle aus der Per­spek­tive des bereit­stellen­den IT-Systems wird mit dem Bau­stein Service in der System­struk­tur doku­men­tiert. Die Spezifi­kation beant­wor­tet alle Fra­gen zur Imple­mentie­rung.
  • Der End­punkt der Schnitt­stelle aus der Per­spek­tive jedes ange­schlos­sene IT-Systems wird mit dem Bau­stein Service als Unter­seite der Start­seite der Schnitt­stelle doku­men­tiert. Die Spezifi­kation beschreibt das Ver­halten des Partner­systems bezo­gen auf die Schnitt­stelle, so wie es verein­bart wurde.
  • Mit dem Bau­stein Event werden Nach­rich­ten­objekte einer event-basier­ten Schnitt­stelle doku­men­tiert.
  • Mit dem Bau­stein Entity werden Infor­mations­objekte einer batch-orien­tier­ten Schnitt­stelle doku­men­tiert.
  • Der Bau­stein Case gibt Ein­blick in die Fähig­keiten der Schnitt­stelle.

Dieses Vor­gehen ver­schafft den Ent­wick­ler der Pro­jekt­organi­sation des Par­tner­systems einen sehr tief­gehen­den Ein­blick in die Reali­sie­rung der Schnitt­stelle. Das för­dert das Ver­ständnis von Daten­struk­turen und beugt Fehlern in der Ver­wendung der Operationen vor. Die hohe Transpa­renz erhöht außer­dem die Chan­cen, dass die »fremden« Ent­wick­ler konstruk­tives Fee­back geben. Das ist ein nicht zu unter­schätzen­der Vor­teil, um Fehler in der Schnitt­stelle früh­zeitig zu identi­fizie­ren.

In vielen Fällen hat die Pro­jekt­organi­sation der Partner­systeme kei­nen Zugriff auf das Wiki oder es gibt eine Vor­gabe des Unter­nehmens, jede Schnitt­stellen­beschrei­bung revi­sions­sicher in einem Doku­menten­manage­ment­system abzu­legen. Dazu wird die Start­seite der Schnitt­stelle mit allen ver­knüpf­ten Bau­steinen aus dem Wiki expor­tiert. Beim Export aus dem Wiki sorgt die Ein­schrän­kung auf die Kennung der Schnitt­stelle, dass nur die für das Partner­system inter­essan­ten Seiten expor­tiert werden. Als For­mat bie­ten sich Word oder PDF an. In beiden Forma­ten blei­ben die Ver­knüpfun­gen inner­halb des expor­tier­ten Doku­mentes erhal­ten.


Feed­back

Leistungs­beschrei­bung für den Auf­trag­geber

Auf­grund der noch immer fehlenden Rechts­sicher­heit bei Gewer­ken mit agiler Soft­ware-Ent­wicklung besteht regel­mäßig der Bedarf an einem Lasten­heft. Arbeiten Auftra­ggeber und Pro­dukt­verant­wort­licher konse­quent mit cards+, dann besteht die Mög­lich­keit, die Leistungs­beschrei­bung für das Lasten­heft zu großen Teilen aus dem Wiki zu expor­tie­ren. Der Auftra­ggeber schreibt das Rahmen­doku­ment und ist Co-Autor der Bau­steine der System­beschrei­bung.

Das Rahmen­doku­ment schreibt der Auf­trag­geber selbst. An die Stelle der Leistungs­beschrei­bung tritt jedoch ein Export der Bau­steine aus dem Wiki, die mit einer ein­deuti­gen Kennung für den Auf­trag als Stich­wort ver­sehen wurden. Jeder Bau­stein Case beschreibt eine einzelne Fähig­keit des IT-Systems. Mit dem Bau­stein Epic werden ver­wandte Fähig­keiten grup­piert. Der Bau­stein Topic schließ­lich legt die Gren­zen des Lasten­heftes fest. Bei IT-Systemen mit einer Bedien­ober­fläche verwendet der Pro­dukt­verant­wort­liche auch den Bau­stein Layout für abge­stimmte Ent­würfe von Fens­ter, Dialo­gen und Mas­ken als Vor­bereitung für die Ent­wick­lung.

Mit diesem Vor­gehen legen Auf­trag­geber und Pro­dukt­verant­wort­liche bereits sehr früh die Grund­lage für die System­beschrei­bung. Wäh­rend der Reali­sierung werden schritt­weise die Lösungen mit den Bau­steinen der System­struk­tur doku­men­tiert. Im Bau­stein Case werden die Essenz­schritte ergänzt. Die Pro­dukt­doku­men­tation wächst mit dem Fort­schritt des Pro­duk­tes. Die ein­deuti­gen Kennung für den Auf­trag als Stich­wort hat den Vor­teil, dass immer erkenn­bar ist, welche Fähig­keiten bereits im ursprüng­lichen Auft­rag gefor­dert wurde und welche erst auf­grund der Erkennt­nisse während der Reali­sierung dazu gekommen sind.

Beim Export aus dem Wiki sorgt die Ein­schrän­kung auf die Kennung des Auf­trages, dass die rich­tigen Seiten expor­tiert wer­den. Als For­mat bie­ten sich Word oder PDF an. In beiden Forma­ten blei­ben die Ver­knüpfun­gen inner­halb des expor­tier­ten Doku­mentes erhal­ten.