Prozesse

Ein­füh­rung in die Pro­dukt­doku­men­tation

Die Ziel­gruppe sind Per­sonen, die neu in der Pro­jekt­organi­sation sind. Die Teil­nahme ist unab­hän­gig von ihrer Rolle im Pro­jekt. Inter­esse ist aber Vor­aus­set­zung. Die Ver­anstal­tung dauert 45 Minu­ten. Es ist ein Fron­tal­vor­trag des Gärtners im Pro­jekt. Maxi­mal 15 Minu­ten sind für Fra­gen wäh­rend der Ein­füh­rung und für Feed­back danach vorge­sehen. Damit dauert die Ein­führung maxi­mal eine Stunde.

Das fol­gende Proto­koll macht Vor­schläge, was ein Vor­tragen­der über eine Pro­dukt­doku­men­tation mit cards+ erzäh­len kann. Passend dazu gibt es eine schritt­weise Anlei­tung für die Gestal­tung des White­boards.

Weiter zum Ergeb­nis.

Pro­­dukt­­doku­­men­­tation

Eine Pro­­dukt­­doku­­men­­tation hat das Ziel, den Zustand eines Pro­dukt­­inkre­­mentes so exakt wie mög­­lich zu beschrei­­ben. Sie exis­­iert im Wiki und wird von Autoren genutzt, um Pro­dukt­wissen und Ergebnisdokumente der nach­haltig zu sichern. Sie bil­det das zen­trale Ver­­zeich­­nis für Spezifi­­kationen, Test­­pläne und anderer für das Pro­­dukt rele­­vanten Unter­lagen. Sie wird über die gesamte Lebens­­zeit eines Pro­­duktes gebraucht. Bei sehr erfolg­­reichen Pro­­dukten sind das Jahr­­zehnte.

Ein Pro­­dukt ent­­steht oder wächst, indem Visi­­onen und Ideen eines Pro­­dukt­­ver­ant­wort­­lichen durch sein Team in Soft­­ware trans­­for­miert werden. Das Ende einer Ite­­ration ist der Zeit­­­punkt, an dem Pro­­dukt­­­doku­­­men­­tation, Code und Test­­­pläne eine Ein­­­heit bil­­den: Das Pro­­dukt­­­inkre­­­ment.

Eine Pro­­dukt­­doku­­men­­tation zerfällt im Wiki grund­sätz­lich in die Bereiche System­­beschrei­­bung, System­­struk­­tur und Archi­tek­tur­ent­wurf.

 

Bau­steine der System­beschrei­bung

In den Bau­steinen der System­­beschrei­­bung geht es kon­kret um den Ver­such, alle Fähig­­keiten des Pro­duktes voll­­ständig und wider­­spruchs­­frei zu erfassen. Sie besteht aus der Doku­­men­tation der Anwen­dungs­­fälle, beson­­derer Situa­­tionen und bekann­ter und aktzep­­tierter Feh­ler des Pro­duktes.

Mit dem Bau­stein Topic wird der Umfang (engl. scope) des Pro­duktes im Über­blick beschrie­ben. Der Bau­stein Epic ent­hält eine fach­liche Beschrei­bung einer Funkt­ionali­tät des Pro­duktes. Der Bau­stein Case ent­hält eine fach­liche Beschrei­bung einer einzel­nen Fähgig­keit des Pro­duktes und die Essenz­schritte der gewähl­ten Lösung.

 

Bau­steine der System­struk­tur

Die Bau­steine der System­­struk­­tur haben das Ziel, die Stru­ktur der Soft­ware zu erfassen, mit Hin­weisen zur Imple­mentierung im Steck­brief und einer kom­pakten Beschrei­bung für das “Ver­ständ­nis”. Sie geben Diensten und Objekten des IT-Systems ein­­deu­­tige Namen. Ein Kompo­­nenten­­über­­blick ist eine gra­fische Visuali­sierung der Topo­logie der Dienste mit ihren Daten­­flüs­­sen, ver­knüpft mit den ent­sprechen­den Seiten im Wiki. Kri­tische Pfade oder gefähr­liche Rück­kopp­lungen im Zusam­men­spiel der Dienste lassen sich so besser erkennen.

Mit dem Bau­stein Domain geben Autoren einer Zusam­men­stellung von Diensten und Objekten mit einer starken Kohä­sion einen ein­deu­tigen Namen. Mit dem Bau­stein Service beschrei­ben wir einen fachl­ichen Dienst. Mit dem Bau­stein Entity beschrei­ben Autoren ein fach­lich rele­vantes Infor­mations­objekt. Mit dem Bau­stein Event beschrei­ben Autoren ein fachlich rele­vantes Nach­richten­objekt. Der Bau­stein Layout ent­hält Ent­würfe oder Skiz­zen eines Teils der Bedien­ober­fläche.

 

Bau­steine für den Archi­tek­tur­ent­wurf

Die Bau­steine für den Archi­tek­tur­ent­wurf erfassen Qualitäts­merk­male, Ent­schei­dungen und Kon­zepte. Ein ganz wich­tiges Ziel des Archi­tektur­ent­wur­fes ist die Dar­stellung und Kommuni­kation des Archi­tektur­stils, der dem Pro­dukt zugrunde liegt.

Der Bau­stein Decision wird ver­wendet, um konse­quent alle funda­menta­len tech­nischen Ent­scheidungen oder vom Auf­trag­geber gefor­derten Quali­täts­merkmale, deren Rück­nahme bzw. Ver­änderung große Aus­wirkung auf das Pro­dukt haben, zu doku­men­tieren.

Der Bau­stein Spec wird ver­wendet, um ein wieder­kehren­des Ent­wurfs­muster bei der Imple­men­tierung (engl. software pattern) oder ein über­greifen­des Kon­zept pro­dukt­spezi­fisch zu beschrei­ben. Pro­dukte anderer Her­steller oder Open-Source-Soft­ware wird eben­falls mit dem Bau­stein Spec doku­men­tiert, weil ent­weder spezi­fische Kon­zepte mit ihrem Ein­satz ver­bun­den sind oder die Ver­wen­dung auf­grund bekann­ter Prob­leme einge­schränkt wird.

 

Spezifi­kationen im Wiki ver­öffent­lichen

Bestimmte Teile vom Code sind geeig­net als Doku­men­tation. Sie ent­hal­ten durch Kommen­tare (z.B. java­doc) wich­tiges Wis­sen. Gleiches gilt für code-nahe Arte­fakte. Eine Kon­figu­rations­datei zeigt sehr genau, welche Para­meter es gibt. Eine Schema­datei beschreibt ein Infor­mations- oder Nach­richten­objekt ganz exakt. Das Team ver­meidet Doku­men­tation, wenn sie diese Ent­wick­lungs­ergeb­nisse für die Ver­öffent­lichung im Wiki nutz­bar machen. Man­che code-nahen Arte­fakte kön­nen direkt ins Wiki hoch­gela­den wer­den, wenn sie vom Team “les­bar” gestal­tet wer­den. Andere Teile vom Code benö­tigen eine Kon­ver­tierung in eine im Wiki ver­wend­bares For­mat (z.B. asciidoc).

Test­pläne im Wiki ver­öffent­lichen

Test­­pläne, organi­­siert in einer Test­­pyra­mide, sichern die Quali­­tät der Soft­­ware ab. Der Bau­stein Case beschreibt eine Fähig­keit der Soft­ware, die mit min­des­tens einem Test­fall abge­sichert wird. In einem Test­fall steckt daher auch wich­tiges Wissen. Das Team ver­meidet Doku­men­tation, wenn sie einen Weg fin­det, die Test­pläne in eine Form zu bringen, die im Wiki ver­öffent­licht werden kann.

 

Prob­lem­raum und Lösung

In den Bau­­steinen der System­­beschrei­­bung wird der Prob­lem­­raum («PR») des Pro­­duktes beschrie­­ben. Sie geben Ant­­wort auf die Fra­gen wer, wann und warum etwas mit dem Pro­dukt tut. Dieser Teil der Doku­­men­tation ist das Ab­bild der Reali­­tät, die Wirk­­lich­­keit aus Sicht der Nutzer des IT-Systems.

Die Bau­­­steine der System­­s­truk­­tur beant­­­wor­­ten hin­­­gegen die Frage, wie das Pro­­­dukt reali­­­siert wurde. Sie beschre­­iben die tat­­säch­­lich vom Team ent­­wickelte Lösung («L»).

Die Bau­­­steine für den Archi­­­tektur­­­ent­­wurf beschrei­­­ben den Lösungs­­­raum («LR») des Pro­­duktes. Der Bau­­stein Decision zeigt nicht nur die gewählte Lösung, sondern auch Alter­­nati­ven, die nicht wei­ter ver­­folgt werden. Mit dem Bau­­stein Spec werden Ent­­wurfs­­muster beschrie­­ben, die auch für zukünf­­tige Imple­mentierungen gel­ten.

Der Bau­­stein Case ist das «missing link» der Pro­­dukt­­doku­­­men­­tation und bildet den Über­­­gang der System­­beschrei­­bung in die System­­s­truk­­tur und umge­­­kehrt. Der Baustein Case ver­bin­det ein kon­kre­tes Prob­lem der Domäne («P») mit einer reali­sier­ten Lösung («L»).

 

Weitere Doku­mente und Unter­lagen

Das Glossar ist eine alpha­betisch sor­tierte Sammlung von Fach­begriffen aus dem Pro­jekt­umfeld. Das Glossar ist das “Wörter­buch” des Pro­jektes. Es ist ein Mini-Lexi­kon, zuge­schnitten auf das Pro­dukt.

Eine Medien­biblio­thek ist ein Kon­zept, um Präsen­tatio­nen (z.B. Power­point oder Key­note), Foto­grafien (z.B. Flip­chart oder White­board), Abbil­dungen und Dia­gramme in ver­schie­denen For­maten an einem zen­tralen “Ort” im Wiki abzu­legen.

Die Link­samm­lung können wir ver­wen­den, um extern ver­wal­tete Doku­mente und Unter­lagen mit einem von uns gewähl­ten Namen im Wiki zu ver­wen­den.

Hand­lungs­anwei­sungen beschrei­ben, wie das IT-System betrie­ben wird. Bei IT-Systemen spielt der Grad der Auto­mati­sierung eine wich­tige Rolle. Für alle Tätig­keiten, die nicht auto­mati­siert werden, gibt es Hand­lungs­anwei­sungen. Sie beschrei­ben Tätig­keiten, die von geschul­tem Per­sonal regel­mäßig oder im Fall einer Stö­rung aus­geführt wer­den.

Hand­­bücher und On­line-Hil­fen geben aus der Pers­pek­tive der Nutzer Ein­­blick in die Fähig­­keiten des Pro­­duktes. Sie erklären den Nutzern den Ein­satz des IT-Systems.

 

Zurück zur Über­sicht.

 

[pdf-embedder]

Die PDF-Datei wird mit dem PDF Embedder angezeigt.