QUALITÄT


Quali­tät

cards+ ist Quali­täts­poli­tik

Quali­täts­poli­tik kennen wir aus dem Sprach­gebrauch der Quali­täts­manage­ment­norm ISO 9001. Mit dem Begriff «Poli­tik» tun sich viele schwer. Im Englischen spricht man von «policy», über­setzt also Strate­gie oder Leit­linie. Und so ist der Ansatz mit cards+ auch zu ver­stehen.

Agile Ent­wick­lungs­­pros­zesse haben sich aus der Erkennt­nis ent­wickelt, dass sich Anfor­derungen für ein IT-System nie so exakt spezifi­zieren lassen, dass kein Spiel­raum für Inter­preta­tionen bleibt. Die Welt dreht sich wäh­rend der Reali­sierung wei­ter. Was heute eine gute Idee ist, kann mor­gen schon ein alter Hut sein.

cards+ hilft bei der Umset­zung der Werte und Prin­zipien aus dem Mani­fest für agile Soft­ware-Ent­wick­lung. Beim Thema Doku­menta­tion ist natür­lich der zwei­te Punkt im Mani­fest beson­ders inter­essant.

Wir schätzen funktio­nierende Soft­ware mehr als umfassende Doku­menta­tion. Mit «wir» ist dabei die ganze Pro­jekt­­­organi­sation gemeint.

Mani­fest für agile Soft­ware-Ent­wick­lung.

Das Ziel beim Ein­satz von cards+ ist keine umfas­sende, sondern eine ange­messene Pro­dukt­doku­men­tation. Autoren im Wiki dürfen bei der Beur­tei­lung der Ange­messen­heit nie ver­gessen, dass Wissen vor allem im Pro­dukt selbst steckt. Wissen wird in Soft­ware trans­formiert. Der größte Teil des Wissens befin­det sich im Code und in den Test­plänen, die den Code prüfen.

Eine Pro­dukt­doku­men­tation muss Quali­täts­merk­male wie Voll­ständig­keit und Richtig­keit auf­weisen. Die ISO 9001 lehrt uns, dass Quali­täts­merk­male mess­bar sein müssen. Voll­ständig­keit wird mess­bar durch die Struk­tur im Wiki, mit Bau­steinen, die einen festen Auf­bau haben. Mode­rierte Kommen­tare geben Autoren ein Maß für die Richtig­keit der Bau­steine.

cards+ ist ein Rahmen, inner­halb dessen Menschen es schaffen, eine kom­plexe Doku­men­tation inkre­mentell zu erstel­len. Sie werden in die Lage ver­setzt, produk­tiv und krea­tiv Fähig­keiten der Soft­ware in mög­lichst ho­her Quali­tät zu beschrei­ben. Bau­steine, Prinzi­pien und Prak­tiken der Methode machen Autoren ihre Arbeit im Wiki so ein­fach wie mög­lich. Trotz­dem kann cards+ keine Feh­ler ver­hin­dern. Sie werden aber sicht­bar.


Quali­tät

cards+ schafft Ord­nung

Das Wiki ist das zen­trale Werk­zeug für den Pro­dukt­verant­wort­lichen. Dort gibt es eine ordent­liche Struk­tur, die er gut kennt, mit Bau­steinen, die er prü­fen kann. Jeder Bau­stein hat seine Ziel­gruppen. Bei jedem Bau­stein ist klar, welche Fähig­keiten ein Autor haben muss.

Das Glossar bringt Ord­nung in Begriffe. Es ist das Wörter­buch des Pro­duktes. Die Begriffe sind das Voka­bular der gemein­samen Sprache. Es ist ein Mini-Lexi­kon, zuge­schnit­ten auf das Pro­dukt. Seine konse­quente Nutzung bedeu­tet, dass Autoren Begriffe in den Tex­ten der Bau­steine mit Ein­trä­gen aus dem Glossar ver­knüpfen. Autoren können ihre Texte dadurch sehr kom­pakt gestal­ten, weil sie Begriffe nicht immer wieder erklä­ren müssen.

Die Medien­­biblio­thek schafft Ord­nung in Bil­der. Sie bil­det einen Kata­log für die Wie­der­­ver­wen­dung von Abbil­dungen und Dia­grammen. Es ent­steht eine gemein­same Bild­sprache. Ver­ände­rungen an einem Bild werden sofort an allen Stellen sicht­bar, es gibt keine zwei Ver­sionen eines Bil­des.

Die zentrale Ver­waltung von exter­nen Links in einer Link­samm­lung folgt der Idee der Medien­biblio­thek. Sie bil­det einen Kata­log für doku­men­tierte Infor­matio­nen außer­halb des Wiki.

Für andere Doku­menten­arten ist das Wiki ein zen­trales Ver­zeich­nis. Spezifi­kationen der Ent­wick­ler werden im Wiki zum Lesen ver­öffentl­icht. Durch das Prin­zip COD gibt es Brücken zu den Arte­fakten der Ent­wick­ler, Tester und Nutzer der Soft­ware. Mit dem Wiki gibt es einen “Ort”, an dem alle doku­men­tier­ten Infor­mationen zen­tral für alle Leser erreich­bar sind.


Quali­tät

Leit­linien von cards+

Die Leit­linien sind der Ver­such, die Methode cards+ auf vier Begriffe zu redu­zieren. Es sind Quali­täts­ziele, die zum Ent­wurf der Struk­tur und der Bau­steine geführt haben.

Nach­haltig­keit

Nach­haltig­keit steht für das Bestre­ben, Wis­sen über ein Pro­dukt perma­nent zu sam­meln und quali­täts­gesichert für alle Ziel­­grup­pen ver­füg­bar zu machen. Es geht um das Ver­spre­chen des Pro­dukt­ver­ant­owrt­lichen, jede Ände­rung am Pro­dukt in der Pro­dukt­doku­men­tation zu ver­öffent­lichen.

Prüf­bar­keit

Alle inter­essier­ten Par­teien sind moti­viert, jede doku­men­tier­te Infor­mation im Wiki zu prü­fen und konti­nuier­lich zu ver­bessern. Sie orien­tie­ren sich an der fes­ten Struk­tur. Sie prü­fen den Auf­bau und In­halt der Bau­steine an­hand abge­stimm­ter und an alle Le­ser kom­muni­zierter Re­geln.

Voll­ständig­keit

Eine voll­stän­dige Pro­dukt­doku­menta­tion stellt ein Pro­dukt in allen Facet­ten dar. Sie ent­hält eine fach­liche und tech­nische Sicht auf das IT-System, ohne sie aber strikt zu tren­nen. Im Gegen­teil. Die Ver­knüp­fung der Bau­steine der System­be­schrei­bung und -struk­tur ist eine Stär­ke dieses An­satzes.

Ganz­heit­lich­keit

Eine ganz­heit­liche Pro­dukt­doku­men­tation be­schränkt sich nicht auf das Wiki. Nicht nur die Bau­steine für System­beschrei­bung, System­struk­tur und Archi­tektur­ent­wurf im Wiki zäh­len, son­dern auch Spezifi­­katio­nen oder Kon­fi­gu­ratio­nen im Code-Reposi­tory oder Test­pläne einer Test­pyra­mide.


Dis­zi­plin

Gemein­same Sprache

Jede Soft­ware hat das Ziel, Prob­leme inner­halb einer Domäne für ihre Nutzer zu lösen. Im Domain-Driven Design geht es nicht nur um die tech­nische Umsetzung, sondern auch um eine bestimmte Denk­weise beim Ent­wurf eines IT-Systems. Der Ansatz stellt die Model­lierung der Fach­lich­keit und die Schaf­fung einer domänen­spezi­fischen Sprache in den Vorder­grund. Die gemein­same Sprache von Domä­nen­exper­ten und Ent­wick­lern ist ein wich­tiges Ziel von cards+ und dem Domain-Driven Design.

Das Glossar enthält u.a. eine Samm­lung von Fach­begriffen aus dem Geschäfts­feld im Unter­neh­men, in dem das IT-System zum Ein­satz kommt. Es enthält Begriffe, die sehr häu­fig ver­wendet werden oder den Domänen­exper­ten beson­ders wich­tig sind. Es ist ein pro­dukt­spezi­fisches Wör­ter­buch, ein Mini-Lexi­kon, zuge­schnit­ten auf das Pro­dukt. Darum ist es ein sehr wert­voller Teil der Pro­dukt­doku­men­tation über den gesamten Lebens­zyklus der Soft­ware. Ein Ein­trag im Glossar ist in der natür­lichen Sprache der inter­essierten Par­teien (z.B. Nutzer) geschrie­ben. Er enthält Erklärun­gen zum Begriff in der pri­mären Sprache des Ent­wicklungs­projektes. In einem inter­natio­nalen Pro­jekt nutzen Autoren das Glossar auch für die Über­setzung von Begriffen in andere Sprachen.

Wichtig ist, dass Autoren konse­quent Quer­ver­weise als Ver­knüpfung zu Ein­trägen im Glossar ver­wenden. Auf diese Weise ver­schafft der Autor dem Leser einen sehr schnellen Zugriff auf weiter­führende Infor­mationen. Der Autor muss wich­tige Begriffe nicht mehr im Text erläu­tern. Die Texte im Wiki werden sehr kom­pakt. Der Autor ver­meidet mehr­fache Beschrei­bungen eines Begriffes im Text. Damit redu­ziert er auto­matisch die Gefahr wider­sprüch­licher Beschrei­bungen.

Die Bau­steine der System­struktur bilden eine weitere wich­tige Grund­lage für die gemein­same Sprache. Dienste und Objekte bekommen im Wiki durch den Seiten­titel einen ein­deuti­gen Namen. Der Name schlägt eine Brücke zum Code und zu den Test­plänen. Voraus­setzung dafür ist, dass Ent­wickler die Seiten­titel der Bau­steine für die Imple­mentierung ver­wendet, wie fol­gende Bei­spiele zeigen:

  • Der Bau­stein Domain repräsen­tiert eine Gitlab-Gruppe.
  • Der Bau­stein Service ist eine gleich­namige Spring-Boot-Anwen­dung.
  • Der Bau­stein Entity wird durch ein POJO reali­siert.
  • Der Bau­stein Event wird durch ein Avro-Schema spezifi­ziert.
  • Der Bau­stein Case gruppiert Test­fälle eines System­tests.

Autoren brauchen nur den Namen eines Diens­tes oder ein Objek­tes des IT-Systems, um sowohl die Beschrei­bung im Wiki als auch die Imple­men­tie­rung im Code-Reposi­tory zu fin­den. Dieses Praxis stärkt außer­dem die gemein­same Sprache, weil Domä­nen­exper­ten auch Begriffe der Ent­wickler kennen — und umge­kehrt.


Quali­tät

Korrekte Sprache

Eine immer wieder­kehrende spannende Frage ist, ob Ent­wick­ler im Code die Begriffe der Anwen­dungs­domäne ins Englische (ihrer lingua franca) über­setzen sollen — oder eben nicht.

Eine gute Über­setzung erfor­dert ein gewisses Maß an Kennt­nissen der Fremd­sprache. In den fol­genden Bei­spielen wird deut­lich, dass selbst dann eine Über­setzung nicht immer ein­deutig ist. Für die Über­setzung des deut­schen Wortes »Zug­fahrt‘ gibt es zwei Mög­lich­kei­ten. Die erste, »train ride‘, ist die Zug­fahrt eines Reisen­den. Die zweite, »train run‘, ist die betrieb­liche Sicht auf eine Zug­fahrt. Das Eng­lische kennt keine Unter­schei­dung zwischen dem Halt (d.h. der Tat­sache, dass ein Fahr­zeug an einem Ort geplant stehen­bleibt) und der Halte­stelle (d.h. einem Ort, an dem solche Halte statt­fin­den können). Beides heißt »stop‘. Es gibt sogar Begriffe im Deut­schen, für die es keine Über­setzung gibt. »Ver­kehrs­tage­schlüs­sel« kann nicht über­setzt werden. Diese numeri­sche Kodie­rung kennt außer­halb Deutsch­lands kaum jemand.

Entscheidet sich der Pro­dukt­verant­wort­liche und das Team gegen eine pau­schale Über­setzung, dann kann das Glossar als Sperr­liste für nicht über­setz­bare Begriffe ver­wen­det werden. Die Regel ist ein­fach: Kein Begriff aus dem Glossar wird im Code über­setzt. Die Folge dieser Ent­schei­dung ist natür­lich Code in einem Sprachen­mix aus deut­schen Begrif­fen ohne Plu­ral mit eng­lischen Ver­ben (z.B. find) und Stereo­typen (z.B. Reposi­tory).

Sehr vor­teil­haft in diesem Zusam­men­hang ist die Ver­mei­dung der Plural­bil­dung. Ein prak­tische Lösung basiert auf der Ver­wendung des Präfix all in allen Fällen, wo Ent­wick­ler im Code einen Bezeich­ner für eine Menge brauchen.

Bitte hier Klicken, um den Quelltext anzuzeigen
interface ZugfahrtRepository {
    Optional<Zugfahrt> findZugfahrtById(String id);
    List<Zugfahrt> findAllZugfahrt();
}

Ein weiterer Vor­teil dieser Praxis ent­steht bei Wor­ten, deren Plu­ral sich nicht vom Singu­lar unter­schei­det (z.B. das eng­lische Wort »infor­mation« oder das deut­sche Wort »Wasser«) oder bei denen der Plur­al eine andere Bedeu­tung hat (z.B. die deut­schen Worte »Geld« bzw. »Gelder«). Dieser Vor­teil ist sogar unab­hängig von der Sprache im Code.

Es gibt aber Ent­wickler, die sich Code nur in Eng­lisch vor­stellen können. Sie finden deut­sche Klassen­namen unzu­mut­bar, grau­sam, inkor­rekt. Andere Ent­wickler schätzen jedoch die Sicher­heit bei der Ver­wen­dung der Begriffe in ihrer Mutter­sprache, einge­bettet in Code. Das ist les­barer Code, den sie ohne Nach­den­ken oder Wörter­buch sofort ver­ste­hen.

Dieser Kon­flikt kann nur im Team geklärt werden. Ein Pro­dukt­verant­wort­licher muss sich jedoch immer klar machen, dass eine Über­setzung der Begriffe einer nicht eng­lischen Domänen­sprache in eng­lische Begriffe im Code ent­gegen dem Wunsch einer gemein­samen Sprache von Domänen­exprten und Ent­wick­ler ist.

Quali­tät braucht Kompe­tenz und Diszi­plin.


Kompe­tenz

Quali­tät ist Kopf­sache

Eine Pro­dukt­doku­menta­tion wird gebraucht, solange das Pro­dukt einge­setzt wird. Ist ein Pro­dukt erfolg­reich, dann sind das mög­licher­weise Jahr­zehnte. In langen Zeit­räumen ändert sich alles. Die Pro­jekt­organi­sation. Die Auf­trag­geber. Die Nutzer. Je reifer ein Pro­dukt ist, desto wich­tiger wird eine ein­fach zu pfle­gende, voll­stän­dige und vor allem rich­tige Pro­dukt­doku­menta­tion.

Pro­dukt­wissen wächst oder ändert sich laufend in einem agilen Umfeld. Es geht um die Frage der Quali­tät von Doku­menten, die schon länger exis­tieren. Sie sind von vielen kleinen Änderungen betrof­fen. Pro­dukt­doku­menta­tion und Pro­dukt dürfen sich aber nicht wider­sprechen. Können Autoren das nicht sicher­stellen, dann ver­dirbt ein Teil der Doku­mente. Das Schlimme an «ver­dor­benen» Doku­menten ist, dass Leser die «faulen Stellen» selten sofort erken­nen. Ver­dor­bene Doku­mente füh­ren ein Team, das an der Ent­wicklung des Pro­duktes arbei­tet, in die Irre. Leider gibt es kein Werk­zeug, mit dem Autoren die Quali­tät von Doku­menten bewer­ten können, so wie Ent­wick­ler bei­spiels­weise mit Sonar­Qube die Quali­tät von Soft­ware in mehreren Dimen­sionen messen können. Moderier­ten Kommen­taren sind eine ein­fache Metrik für eine Seite im Wiki. Die Seiten­vor­lagen als Proto­typ für eine Seite sorgt für einen ein­heit­lichen, formal prüf­baren Inhalt. Jede gemäß Seiten­vor­lage des Bau­steins voll­ständige Seite ohne Kommen­tare ist daher eine «gute» Seite. Und das lässt sich auf eine Blick erken­nen.

Quali­tät ist das Ergeb­nis der gemein­samen Anstren­gun­gen aller Autoren und Leser. Es ist Kopf­sache.


Diszi­plin

Quali­tät durch Beschrän­kung

Jede Per­son in der IT-Branche hat seine eigene Vor­stel­lung von guter Doku­men­tation. Diese Vor­stellung ist ganz maß­geblich von persön­lichen Schwer­punkten oder seiner Rolle bestimmt. Auch bei der Wahl des »richtigen« Werk­zeugs zum Schrei­ben der Doku­mentation gibt es unter­schied­liche Vor­lieben.

  • Ein Pro­dukt­verant­wort­licher nutzt Office-Pro­dukte oder ein Wiki (z.B. Confluence).
  • Ent­wick­ler nutze gerne Markup-Dateien, weil die sich wie Code ver­halten.
  • Tester denken in Tabellen oder Listen und nutzen Office-Pro­dukte (z.B. Excel) oder spezielle Werk­zeuge (z.B. Fitnesse).
  • Administra­toren schätzen Betriebs­anwei­sungen und Hand­bücher online in einer Wissens­daten­bank.

»Viele Köche verderben den Brei« ist ein Sprich­wort, das wahr wird, wenn jede an der Pro­dukt­ent­wick­lung beteiligte Per­son »seinen« Teil der Pro­dukt­doku­mentation so schreibt, wie sie nach persön­lichen Gesichts­punk­ten für rich­tig hält. Der Eins­atz von cards+ und die Ein­führung eines Wiki als zen­tralen Ort für die Pro­dukt­doku­mentation ändert die Situa­tion. Der Pro­dukt­verant­wort­liche und das Team arbei­ten mit Werk­zeugen, die opti­mal auf­einander abge­stimmt sind. Eine Grund­regel bei cards+ lautet daher: Ein Autor erfasst nur In­halte im Wiki, für die er einen passen­den Bau­stein findet.

Ent­wick­ler schrei­ben Spezifi­kationen für Dienste und Objekte mit den gleichen Werk­zeugen, mit den sie auch pro­gram­mie­ren. Tester erarbei­ten ihre Test­pläne in ihrem gewohn­ten Werk­zeugen. Die Spezifi­kationen und Test­pläne werden nach ihrer Frei­gabe für das Pro­dukt­inkre­ment vom Team zum Lesen im Wiki ver­öffent­licht. Es liegt in der Verant­wortung des Teams, ein geeig­netes Format zu wählen, das im Wiki direkt nutz­bar ist oder leicht für die Ver­wendung im Wiki konver­tiert werden kann.

Quali­tät ent­steht durch Beschrän­kung der Viel­falt durch klare Regeln. Regeln, auf deren Ein­hal­tung der Gärtner ach­tet.


Diszi­plin

Quali­tät durch Simpli­zität

Das Prin­zip PLA ist eine gol­dene Regel in der Soft­ware-Ergo­nomie, Mensch-Com­puter-Inter­aktion und dem UX-Design. Das Prin­zip lässt sich gut auf Doku­men­tation über­tragen. Jeder Leser wünscht sich Infor­mationen so aufbe­reitet, dass er sie gut auf­nehmen kann. Im Wiki findet er eine Doku­menta­tion mit einer nach­voll­zieh­baren Struk­tur. In den Bau­stei­nen findet er genau die doku­mentier­ten Infor­matio­nen, die er dort erwar­tet. Er kann gezielt den Ver­knüpfun­gen zwischen den Bau­steinen fol­gen oder ein­fach suchen. Er kann jeder­zeit Feed­back als Kommen­tar abge­ben.

Ein ein­fach zu bedienen­des Wiki bringt mehr Quali­tät durch Zusam­men­arbeit. Nur ein Wiki mit ein­facher Struk­tur und ver­ständ­lichen Inhal­ten erreicht auf Dauer alle Leser.


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 ei­nen Teil des Pro­dukt­wis­sens kor­rekt er­fasst. Das Glos­sar bil­det die Grund­lage für das Voka­bular. Ein Text mit Begrif­fen aus dem Glos­sar, vom Au­tor rich­tig ver­wen­det, ist da­her kor­rekt, wenn wir da­von aus­gehen, dass die Ein­träge Im Glos­sar kor­rekt sind. Le­ser kön­nen die Tex­te mit den Er­klä­run­gen im Glos­sar sehr leicht über­prü­fen. Sprach­liche Rich­tig­keit (Ortho­gra­phie, Gram­matik, Aus­druck) der Texte wird grund­sätz­lich vor­aus­ge­setzt.

Voll­stän­dig­keit

Ein Bau­stein der Pro­dukt­doku­men­tation ist voll­stän­dig, wenn der Au­tor die rich­tige Sei­ten­vor­lage ver­wen­det und alle Ab­schnit­te mit In­halt füllt. Tritt der Fall ein, dass ein Au­tor einen Ab­schnitt in ei­nem Bau­stein nicht sinn­voll aus­fül­len kann, dann wird ge­nau die­ser Um­stand mit einem Leer­ver­merk wie «Keine An­gabe» oder «Nicht zu­tref­fend» und ge­ge­be­nen­falls mit einer Be­grün­dung doku­men­tiert. Leer­ver­mer­ke ma­chen ei­nen Bau­stein voll­stän­dig, und in der Kon­se­quenz auf Voll­stän­dig­keit prüf­bar.

Über­sicht­lich­keit

Eine klare, über­sicht­liche Dar­stel­lung der In­halte trägt wesent­lich zur Akzep­tanz der Pro­dukt­doku­men­tation bei den Le­sern bei. Der ein­heit­liche Auf­bau der Bau­stei­ne unter­stüt­zt Au­to­ren in die­sem Vor­ha­ben. Die Bau­stei­ne der Sy­stem­be­schrei­bung sind streng hierar­chisch auf­ge­baut und auf maxi­mal zwei Über­schrif­ten­ebe­nen be­schränkt. In den Bau­stei­nen der Sy­stem­struk­tur gibt es immer einen Steck­brief als Ein­stieg und den Ab­schnitt Spezi­fi­kation für Im­ple­men­tie­rungs­de­tails als Ab­schluss.

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 Au­tor sein Pro­dukt­wis­sen. Die Ver­knüp­fung von Be­grif­fen im Text mit Ein­trä­gen im Glos­sar för­dert das Ver­ständ­nis für den Le­ser. Gleich­zeitig ist es eine Maß­nahme für den Au­tor, den Text kom­pakt zu hal­ten. Ein gut ge­pfleg­tes Glos­sar dient hier als Mini-Lexi­kon des Pro­duk­tes.


Kompe­tenz

Feed­back durch Provo­kation

In der Soft­ware-Ent­wicklung arbei­ten Menschen sehr inten­siv zusam­men. Über kurz oder lang ent­stehen in jedem Team Kon­flikte. Provo­zierte Kon­flikte soll­ten aller­dings die Aus­nahme sein. Provo­kation ist sehr häufig nega­tiv belegt. Eine Provo­kation ist dann erfolg­reich, wenn der Provo­zierte zu einer Reak­tion genö­tigt wurde.

Wird ein Leser im Wiki durch den Autor mit dem Wissen anderer kon­fron­tiert, dann kann der Leser auf­grund seines eigenen Wissens Fehler oder Lücken identi­fizieren. Im Wiki gibt er Feed­back dazu. Ganz ent­spannt als Kommen­tar, aber trotz­dem für alle anderen sicht­bar. Die not­wen­digen Voraus­setzun­gen für so eine posi­tiv wir­kende Provo­kation sind schnell aufge­zählt:

  1. Jeder kennt die Doku­mentation und ihre Stru­ktur.
  2. Die Doku­mentation wird von allen ver­wendet.
  3. Die Doku­mentation wird von allen ver­bessert.

Mit dem Ein­satz von cards+ erfül­len Autoren die Voraus­setzung für Punkt 1 der Liste. Die Bau­steine und die fixe Seiten­struk­tur stellen sicher, dass jeder weiß, wo wich­tige Infor­mationen zu fin­den sind. Mit Ver­knüpfungen in den Seiten führt der Autor seine Leser durch die Doku­mentation. Die Such­funk­tion erlaubt flexi­ble Recher­chen. Die konse­quente Nutzung von Schlagw­orten in den Seiten macht Zusammen­hänge mit einem Klick sicht­bar. Punkt 2 der Liste ist Teil der Kul­tur der Pro­jekt­organi­sation. Das Wiki ist ein akzep­tiertes Werk­zeug für Kommuni­kation im Team. Ganz wichtig ist, dass die Pro­dukt­doku­menta­tion als Wahr­heit gilt. Eine klare Abgren­zung zur Pro­jekt­doku­mentation ist wichtig. Mit Punkt 3 der Liste ist der Pro­zess für konti­nuier­liche Ver­besserung gemeint.

Voll­ständig­keit ist keine Voraus­setzung, die wollen Autoren neben Korrekt­heit durch das provo­zierte Feed­back bei den Lesern erreichen. Die Idee von “collective code ownership”, wie sie bei­spiels­weise Martin Fowler in seinem Bliki beschreibt, lässt sich leicht auf eine Pro­dukt­doku­mentation erwei­tern. Jeder ist Autor und ver­öffent­licht sein Wissen im Wiki. Jeder ist Leser und profi­tiert vom Wissen Anderer.

Die Quali­tät der Inhalte ist das Ergeb­nis der Gemein­schaft, getrie­ben durch Feed­back. Keinen Leser lässt es kalt, wenn in »seiner« Produkt­doku­menta­tion ein offen­sicht­licher Fehler steckt.


Diszi­plin

Feed­back ein­fach so

Eine rich­tige Doku­mentation ist immer eine große Heraus­forderung. Autoren im Wiki stellen sich dieser Heraus­forderung als Gemein­schaft und nutzen das Feed­back aller Leser. Feed­back einfach so zu geben, ohne extra aufge­for­dert zu werden, muss darum Teil der Kul­tur in einer Projekt­organi­sation sein.

Richtig­keit ist ein Ergeb­nis konti­nuier­licher Verbes­serung, getrie­ben vom Feed­back aller Beteilig­ten, moti­viert durch den sehr gerne zitier­ten Grund­satz für Retro­spek­tiven, der soge­nann­ten obersten Direktive (engl. prime directive).

Unab­hängig davon was wir ent­decken werden, ver­stehen und glau­ben wir auf­richtig, dass in der gege­benen Situation, mit dem verfüg­baren Wissen und Ressourcen und unseren indivi­duellen Fähig­keiten, jeder sein bestes getan hat.

Norman L. Kerth

Mit ande­ren Wor­ten: Auch Autoren machen Fehler. Und das dürfen sie auch. Es muss aber ein natür­licher Reflex jedes Lesers sein, einen Kommen­tar im Wiki zu hinter­lassen, wenn er einen Fehler ent­deckt. Jeder Ent­wick­ler kennt einen Teil des IT-Systems sehr gut. Hat er Kennt­nis von einer Fähig­keit in der Soft­ware, die im Wiki nicht zu finden ist, dann gibt er den Autoren mit seinem Kommen­tar einen wich­tigen Hin­weis. Ent­wick­ler ver­setzen mit ihrem Feed­back Autoren in die Lage, Lücken schnell schlie­ßen.

Konti­nuier­licher Verbes­serung ist Verbes­serung in kleinen Schrit­ten. Die Initia­tive der «clean code developer» formu­liert dieses stete Bemühen als Pfad­finder­regel.

Jede Beschäf­tigung mit einem Gegen­stand macht ihn zumin­dest ein klein wenig besser. Ganz ohne büro­kra­tische Pla­nung.

clean code developer

Diese im Grunde genom­men sehr ein­fache Regel ver­hindert, dass das Wiki an Akzep­tanz ver­liert, weil in den Seiten Lücken und kleine Fehler ent­halten sind. Wir kennen das Phäno­men auch als Theorie der zer­brochenen Fenster.

Wird eine zer­brochene Fenster­scheibe nicht schnell repa­riert, sind im Haus bald alle Scheiben zer­brochen.

James Q. Wilson und George L. Kelling

Nach ihr beginnt der Verfall von Quali­tät im allge­meinen Sinn mit Kleinig­keiten, die nur lange genug unbe­achtet blei­ben. Darum ist es essen­tiell, dass jeder Leser weiß, dass seine Mit­arbeit wich­tig ist. Autoren sind aufge­fordert, wert­schätzend mit diesem so wert­vollen Feed­back umzu­gehen.


Kompe­tenz

Feed­back für 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.

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 jede komp­lexe Auf­gabe beherrsch­bar.

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

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.

Der Pro­dukt­verant­wort­liche hat immer die Mög­lich­keit, die Ergeb­nisse aus dem agi­len Ent­wick­lungs­pro­zess direkt im Wiki nach­zule­sen. Die Entwickler müssen dafür nur sorg­fältig die klei­nen Korrek­turen an den Spezifi­kationen gleich­zeitig mit den Änderungen am Code machen. 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.

Die Ver­öffent­lichung im Wiki läßt sich auto­mati­sie­ren. Ihr Aus­löser ist die Frei­gabe des Pro­dukt­inkre­ments. Ein Bonus moder­ner Soft­ware-Ent­wick­lung.


Defi­nition

Welche Kate­gorien von Quali­täts­merk­malen gibt es?

Benutz­bar­keit

Be­nutz­bar­keit (engl. usabi­lity) ist die Fähig­keit der Soft­ware, Stan­dards, Kon­ven­tio­nen, Stil­vorg­aben (engl. style guides) oder Vor­schrif­ten bezo­gen auf die Be­nutz­bar­keit ein­zu­hal­ten. Be­nutz­bar­keit ist eng ver­wandt mit dem Begriff Ge­brauchs­taug­lich­keit, der Eig­nung ei­nes Pro­duk­tes, die von Nutzern ange­streb­ten Ziele effek­tiv, effi­zient und zufrie­den­stel­lend zu errei­chen.

Effi­zienz

Effi­zienz (engl. effi­ciency) ist das Ver­hält­nis zwi­schen dem Leis­tungs­ni­veau der Soft­ware und dem Um­fang der ein­ge­setz­ten Be­triebs­mit­tel un­ter fest­geleg­ten Be­dingun­gen. Effi­zienz wird in der Praxis oft­mals ver­ein­facht als Leis­tungs­fähig­keit (engl. perfor­mance) be­zeich­net, mit den Aspek­ten Verar­bei­tungs­ge­schwin­dig­keit, Ant­wort­zeit, Durch­satz, Spei­cher­be­darf oder Men­gen­ge­rüs­te.

Funktio­nali­tät

Funk­tio­nali­tät (engl. functio­nality, func­tional suita­bility) ist das Vor­han­den­sein von Funk­tio­nen mit ange­forder­ten Ei­gen­schaf­ten. Fun­ktio­nale Soft­ware be­sitzt ei­nen ange­messe­nen Um­fang und ist ord­nungs­gemäß reali­siert. Da aber ein Soft­ware-Test nur die An­wesen­heit, aber nicht die voll­stän­dige Ab­wesen­heit von Feh­lern zei­gen kann, ist eine feh­ler­freie Soft­ware eher als nie er­reich­bares Ziel zu sehen.

Kompa­tibili­tät

Kompa­tibili­tät (engl. com­pati­bility), auch Inter­opera­bili­tät, kenn­zeich­net die Fähig­keit der Soft­ware von min­des­tens zwei IT-Syste­men, Da­ten unter­ein­ander aus­zu­tau­schen, die­se Da­ten kor­rekt zu inter­pre­tie­ren und zu ver­ar­bei­ten. Bei Kompa­tibili­tät im Sin­ne von Ko­exis­tenz geht es vor allem da­rum, dass die Soft­ware nur jene Res­sour­cen ver­braucht, die ihr zuge­wiesen wer­den.

Porta­bili­tät

Porta­bili­tät (engl. porta­bility) ist die Eig­nung der Soft­ware, von der Umge­bung in eine andere über­tra­gen wer­den zu kön­nen. Da­raus lei­tet sich der An­spruch ab, dass Soft­ware leicht in­stal­lier­bar und Kompo­nen­ten der Soft­ware leicht aus­tausch­bar sind. Porta­bili­tät ist eine Vor­aus­setzung für die Auto­ati­sierung der Instal­lation von Soft­ware.

Sicher­heit

Sicher­heit (engl. secu­rity) ist ein Sam­mel­begriff für alle Fähig­kei­ten einer Soft­ware, die not­wendig sind, um Da­ten und das IT-System so zu schüt­zen, dass beab­sich­tigte Zu­grif­fe erkannt und uner­laubte Zu­grif­fe abge­wehrt wer­den. Das bein­haltet den Nach­weis von manu­ellen Ein­grif­fen (engl. auditing).

Wart­bar­keit

Wart­bar­keit (engl. main­taina­bility) ist ein Sam­mel­begriff für Ände­run­gen mit dem Ziel, Korrek­turen, Ver­besse­run­gen oder An­passun­gen an der Soft­ware für neue An­for­derun­gen oder geän­der­ten Quali­täts­merk­malen durchzu­füh­ren. Eine Soft­ware gilt als wart­bar bzw. gut änder­bar, wenn der Auf­wand für die Durch­füh­rung von Ände­rungen ge­ring ist.

Zuver­lässig­keit

Zuver­lässig­keit (engl. relia­bility) ist die Fähig­keit der Soft­ware, ihr Leis­tungs­niveau unter fest­geleg­ten Be­dingun­gen über einen fest­geleg­ten Zeit­raum zu bewah­ren. Über Ver­füg­bar­keit er­folgt die Fest­legung, in­wie­weit eine An­wen­dung rund um die Uhr ver­füg­bar ist. Wei­tere Merk­male sind die Wieder­her­stell­bar­keit und die Fehler­tole­ranz eines IT-Systems.


Kompe­tenz

Quali­täts­merk­male

Für die Beur­teilung der Quali­tät von Soft­ware gibt es Quali­täts­merk­male. Die Quali­täts­manage­ment­norm ISO 25010 macht Vor­schläge für die Kate­gori­sie­rung von Quali­täts­merk­malen. Eine voll­stän­dige und kor­rekte Pro­dukt­doku­men­tation ist bereits ein nicht zu unter­schätzen­des Quali­täts­merk­mal einer Soft­ware in Bezug auf die Kate­gorie Wart­bar­keit. Mit anderen Worten unter­stützt ein Wiki mit Bau­steinen der Methode cards+ die Erfüllung von Quali­täts­merk­malen der Kate­gorien Funktio­nali­tät und Wart­bar­keit.

Mit dem Bau­stein Decision begrün­det der Pro­dukt­verant­wort­liche oder Ver­tre­ter des Teams eine wichtige Ent­schei­dungen, die große Aus­wir­kung auf die Soft­ware hat oder den Lösungs­raum ein­schränkt. Jede Ent­schei­dung wird min­destens einem Quali­täts­merk­mal zuge­ordnet, mit einer Begrün­dung, die erklärt, warum sie für dieses Quali­täts­merk­mal rele­vant ist. In der Pro­dukt­doku­men­tation gibt es zu jedem Quali­täts­merk­mal mindes­tens eine Ent­scheidung oder ein Kon­zept mit einer Aus­sage, wie und in welchem Umfang das Quali­täts­merk­mal in der Soft­ware umge­setzt wurde.

Mit dem Bau­stein Spec doku­men­tieren Ent­wickler über­grei­fende oder wieder­holt einge­setzte Kon­zepte, die u.a. sicher­stellen, dass eine Soft­ware bestimmte Quali­täts­merk­male auf­weist.

Bitte hier Klicken, um das Fallbeispiel anzuzeigen

Wart­bar­keit

Ana­lysier­bar­keit

Die Decision Begriffe der Domäne im Code sorgt dafür, dass sich eine gemein­same Sprache aus den Begriffen der Domäne ent­wickeln kann. Les­barer Code ist das Ziel.

Die Decision Pro­gram­mier­sprache für Indi­vidual­entwick­lung legt eine Stan­dard­pro­grammier­sprache fest. Eine Abwei­chung muss gut begrün­det sein und darf nicht aus einer “Laune heraus passieren”.

Gemäß Spec Event-basierte Mess­punkte kann jeder Dienst zur Lauf­zeit soge­nannte Mess­punkte in beson­dere Situa­tionen erzeu­gen. Ein Mess­punkt ist ein­deutig identi­fizier­bar, doku­men­tiert Zeit­punkt und Zuord­nung zu einem Dienst, beschreibt die Situa­tion (z.B. ein Daten­satz kann nicht ver­arbei­tet werden) und ent­hält alle Daten, die für eine spätere die Ana­lyse not­wendig sind.

Modularität

Der gewählte Archi­tektur­stil pipes and filters basiert auf folgenden Grund­kon­zepten für Dienste:

Es gibt zwei Lösungs­ansätze für Schnitt­stel­len von Diensten:

Modifizierbarkeit

Die Decision Ver­sions­ver­wal­tung in Git legt eine nach­voll­zieh­bare Stra­tegie für die Versio­nierung der Code-Basis fest.

Die Decision Continuous Inte­gration mit Git legt den Grund­stein für hohe Code-Quali­tät.

Prüfbarkeit

Die Decision Werk­zeug für Android-UI-Tests legt den Grund­stein für auto­mati­sier­bare Test­aus­füh­rung für die Android-App.

Die Decision Werk­zeug für Schnitt­stel­len­tests legt den Grund­stein für auto­mati­sier­bare Test­aus­füh­rung für Dienste.

Die Decision Werk­zeug für Sys­tem­tests legt den Grund­stein für auto­mati­sier­bare Test­aus­füh­rung für das IT-System.

Stabilität

Apache Kafka ist eine Platt­form für ein sehr gut skalier­bares ver­teil­tes IT-Systems mit einer event-basier­ten Daten­ver­arbei­tung nahezu in Echt­zeit. Der Einsatz von Apache Kafka als Platt­form für messaging hat sich im Labor­ver­such bewährt.

Apache Cassandra ist ein Ver­tre­ter der spalte­norien­tier­ten Daten­banken, der sich bei gro­ßen Daten­mengen mit hoher Skalier­bar­keit anbie­tet. Der Einsatz von Apache Cassandra als ver­teilte Daten­bank hat sich im Labor­ver­such bewährt.

Der Ein­satz von Spring Boot als Grund­gerüst für jeden Dienst sorgt für ein ein­heit­liches und nach­voll­zieh­bares Ver­halten bei der Daten­ver­arbeitung.

Der Ein­satz von Apache Kafka Streams ermög­licht eine leicht­gewichtige Lösung für streaming ohne Abhängig­keiten zu anderen Diensten.

Mit diesem Vor­gehen kehrt der Pro­dukt­verant­wort­liche die weit ver­breitete Praxis um, nicht funk­tionale Aspekte wie Fähig­keiten anzu­for­dern. Quali­täts­merk­male werden nicht ein­fach program­miert. Sie sind Eigen­schaf­ten einer Soft­ware, die durch die Wahl des Archi­tektur­stils, durch den Ein­satz bestimm­ter Infra­struk­tur oder Anwen­dung bestimm­ter Entwurfs­muster ent­stehen. Quali­täts­merk­male beein­flussen sich gegen­seitig. Häufig »zerren« sie von zwei Seiten, d.h. stärkt man ein Quali­täts­merk­mal, schwächt man ein anderes. In einem verteilten IT-System kann bei­spiels­weise die Opti­mierung des Zeit­ver­hal­tens bei der Daten­ver­arbeitung die Ana­lysier­bar­keit bein­trächti­gen. Das CAP-Theo­rem ist ein weiteres Bei­spiel für dieses Dilemma.

Das CAP-Theo­rem oder Brewers Theo­rem besagt, dass es in einem ver­teil­ten System unmög­lich ist, gleich­zeitig die drei Eigen­schaf­ten Konsis­tenz (engl. consistency), Verfüg­bar­keit (engl. availability) und Aus­fall­tole­ranz (engl. partition tolerance) zu garan­tieren.

Eric Brewer

Ein weiterer nicht zu unter­schätzen­der Vor­teil ist der Über­blick zu jedem einzel­nen Quali­täts­merk­mal, der sich aus der Verknüpfung der Bau­steine Decision und Spec mit dem Quali­täts­merk­mal ableiten läßt. Diese kom­pakte Zusammen­stellung von Ent­scheidungen und Kon­zepten zu einem Thema zeigt Abhängig­keiten, die sonst nicht so leicht erkenn­bar sind.


Diszi­plin

Quali­täts­manage­ment

Steuerungs­maß­nahmen für den Ent­wicklungs­prozess, wie sie in der Quali­täts­manage­ment­norm ISO 9001 von einer Organi­sation gefordert werden, sind nur mit genauer Kennt­nis der Ent­wick­lungs­erge­bnisse mög­lich. Der Ein­satz von cards+ und dem damit ver­bundenen Vor­haben, eine ange­messene und mit der ent­wickel­ten Soft­ware wachsende Pro­dukt­doku­men­tation zu erstel­len und zu pflegen, eröff­net eine Reihe von Mög­lich­keiten zur Veri­fizierung der Ent­wicklungs­ergeb­nisse. Eine wesent­liche Eigen­schaft von cards+ ist die fixe Struk­tur im Wiki, mit Bau­steinen, Prinzi­pien und Prak­tiken, die opti­mal auf­einander abge­stimmt sind.

Der Bau­stein Topic hilft, den Umfang (engl. scope) eines IT-Systems fest­zule­gen und klare Gren­zen für die Ent­wick­lung zu zie­hen. Alle Topics zusammen beschrei­ben den Pro­jekt­auf­trag, über­setzt in die Sprache des Pro­duk­tes.

Der Bau­stein Case wird ver­wendet, um eine Fähi­gkeit des IT-Systems zu beschrei­ben. Mit dem Bau­stein Epic werden eng ver­wandte Fähig­keiten zu einer kom­pletten Funktio­nali­tät zusam­men­gefasst. In der Sprache der Norm sind das die Ent­wicklungs­ein­gaben. Eine Soft­ware, die »fertig« ist, hat für jeden Case eine Lösung oder eine Begrün­dung, warum eine Lösung nicht mög­lich oder not­wendig ist. Auf dieser Grund­lage kann der Pro­dukt­verant­wort­liche sehr gut beur­teilen, ob alle Ent­wick­lungs­einga­ben bei der Reali­sierung vom Team berück­sich­tigt wurden.

Das Testen einer Soft­ware hat nicht die voll­stän­dige Prüfung aller Fähig­keiten zum Ziel. Das wird in der IT-Branche heut­zutage als unmög­liches Vor­haben einge­schätzt. Eine Metrik wie die Test­abdeckung durch Modul-, Schnitt­stellen- und System­tests ver­setzt den Pro­dukt­verant­wort­lichen in die Lage, Quali­täts­ziele für die Ent­wick­lung zu defi­nie­ren. Der Ein­satz von cards+ lässt ihn auch beim System­test eine Quali­täts­ziel defi­nieren. Jeder Case in der System­beschrei­bung mit einer Lösung muss durch mindes­tens einen Test­fall im System­test abge­sichert werden. So ist der Beweis erbracht, dass die Soft­ware min­destens alle in der Pro­dukt­doku­men­tation erfassten Fähig­keiten besitzt.


Defini­tion

Was zählt zur Leistung­beschrei­bung eines Pro­duk­tes?

Bau­stein Topic

Der Bau­stein Topic gibt den Um­fang (engl. scope) des Pro­duk­tes vor. Hier wird Be­zug auf die Unter­neh­mens­pro­zes­se ge­nom­men.

Bau­stein Epic

Der Bau­stein Epic grup­piert ver­wandte Fähig­kei­ten zu Funk­tio­nali­tä­ten. Hier be­fin­den sich auch Aus­schlüs­se und Ab­gren­zun­gen.

Bau­stein Case

Der Bau­stein Case be­schrei­bt eine ein­zelne ge­for­der­te Fähig­keit der Soft­ware und nach dem Ab­schluss der Reali­sie­rung mit den Es­senz­schrit­ten die Lö­sung.

Bau­stein Decision

Mit dem Bau­stein Decision werden vom Auf­trag­ge­ber ge­for­derte Quali­täts­merk­male der Soft­ware mit Be­grün­dung fest­ge­hal­ten.

Bau­stein Layout

Der Bau­stein Layout wird für die Siche­rung der Ent­würfe ei­ner Be­dien­ober­flä­che ver­wen­det, die mit dem Auf­trag­ge­ber ab­ge­stimmt wur­den.

Bau­stein Service

Den Bau­stein Service dient der Fest­le­gung von Schnitt­stel­len des IT-Sys­tems nach au­ßen. Er be­schreibt das API und die End­pun­kte auf bei­den Sei­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.


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.