STRUKTUR


Struk­tur

cards+ hat klare Regeln

Die Pro­dukt­­doku­men­tation umfasst das gesamte Wissen zu einem Pro­dukt­­inkre­ment. Sie beschreibt den Zustand eines Pro­duktes zu einem bestimmten Zeit­punkt. Sie ist nicht auf das Wiki beschränkt. Das Wiki bil­det jedoch das zen­trale Ver­zeich­nis für die Doku­men­tation.

Eine voll­­­stän­dige Pro­dukt­­doku­mentation muss als sol­che erkenn­bar sein. Autoren brau­chen prüf­bare Regeln für den Auf­bau und Inhalt im Wiki in einer klar kommuni­­zier­ten Struk­tur mit vor­definier­ten Bau­steinen. Jeder Bau­stein hat genau einen Zweck und bestimmte Ziel­gruppen. Autoren wissen, was in den Bau­stein gehört und was nicht. Diese Abgren­zung ist sehr wich­tig.

Die exakte Defini­tion der Bau­steine ist Autoren und Lesern gleicher­maßen bekannt. Bau­steine stellen Vor­gaben für Autoren dar, wie es sie auch in Form von Pro­gram­mier­­­richt­­­linien für Ent­wick­ler gibt. cards+ unter­­­stützt so Autoren bei dem Vor­haben, die Seiten im Wiki aktu­ell und fehler­frei zu hal­ten. Leser aus der Pro­jekt­­­organi­sation können durch die ein­­­heit­liche Gestal­tung der Bau­steine den Inhalt besser ein­ordnen. So können sie ziel­­­gerich­tet Feed­back geben.

System­­beschrei­bung

In den Bau­stei­nen der System­­beschrei­­bung werden die Gren­zen des IT-Systems defi­nie­rt und alle Fähig­­kei­ten der Soft­ware voll­­ständig, wider­­spruchs­­frei und hierar­chisch erfasst. Fähig­­keit ist der Sammel­begriff für Anwen­dungs­­fälle, beson­­derer Situa­­tio­nen und bekann­ter und akzep­­tier­ter Feh­ler des IT-systems.

System­­struk­tur

Die Bau­steine der System­­struk­­tur haben das Ziel, die Stru­ktur der Soft­ware korrekt zu erfassen und einen Über­blick über das Zusam­men­­spiel der Dienste und Objekte zu geben. Ein nach­­rich­ten-orien­­tier­ter Archi­tektur­­stil ergibt eine andere System­­struk­tur als die Reali­­sierung eines IT-systems mit einem Appli­­kations­­ser­ver.

Archi­tektur­ent­wurf

In den Bau­stei­nen für den Archi­tek­tur­ent­wurf werden die vom Auf­trag­geber gefor­derten Quali­täts­merk­male, funda­menta­le Ent­schei­dungen und über­greifende Kon­zepte nach­voll­zieh­bar erfasst. Ein ganz wich­tiges Ziel des Archi­tektur­ent­wur­fes ist die Dar­stellung und Kommuni­kation des Archi­tektur­stils.

Das Meta­modell der Bau­steine der Pro­dukt­doku­men­tation.


Problem­raum

Bau­steine der System­beschrei­bung

Unter dem Sammel­begriff System­beschrei­bung bündelt cards+ Bau­steine für Fähig­keiten einer Soft­ware. Die Bau­steine sind streng hierar­chisch aufge­baut, vom Groben ins Feine. An der Spitze steht der Gege­nstand (engl. topic, theme) für die Ent­wick­lung. Die sehr abstrakte Sicht auf den Aufgaben­bereich, in dem sich das Pro­dukt bewegt, wird voll­ständig und wider­spruchs­frei in Funktio­nali­täten und Fähig­keiten zer­legt. Zur System­beschrei­bung zäh­len auch »Ver­ständnis­modelle«, die wichtige Zusam­men­hänge aus fach­licher Sicht erklä­ren.

Die System­beschrei­bung ist jedoch keine Anfor­­derungs­­doku­­mentation.

Der Pro­dukt­­verant­wort­liche nutzt die Bau­steine der System­beschrei­bung, um so früh wie mög­lich seine Vision des Pro­duktes zu kon­kreti­­sieren. Er tut das am besten bereits beim Start des agilen Ent­wick­lungs­pro­jektes, unter Ein­­bezie­hung des Auf­trag­­gebers. Er hat die Mög­lich­keit, pro­dukt­spezi­fische Funktio­­nalitä­ten und Fähig­keiten der Soft­ware früh­­zeitig einen Namen zu geben. Ein guter Titel legt so den Grund­stein für eine gemein­same Sprache von Auf­trag­­geber, Pro­dukt­verant­wort­lichen und dem Team. Inter­essierte Par­teien können sich jeder­zeit einen sehr kom­pakten Über­blick über den Umfang des Pro­duktes ver­schaffen.

Bau­stein Topic

Der Bau­stein Topic beschreibt einen klar abge­grenz­ten Auf­gaben­bereich (engl. scope), in dem das IT-System Ver­wen­dung fin­det. Er ver­mit­telt einen Über­blick über den Auf­gaben­bereich mit Bezug auf die Unter­nehmens­pro­zesse. Er bün­delt eine mit den Anfor­derun­gen wach­sende Menge von Funktio­nali­täten, die mit dem Bau­stein Epic doku­mentiert wer­den.

Bau­stein Epic

Der Bau­stein Epic gibt einer pro­dukt­spezi­fischen Funk­tio­nali­tät einen ein­deu­tigen Namen und ent­hält eine fach­liche Beschrei­bung. Er bün­delt eine mit den Anfor­derun­gen wach­sende Menge von fach­lich verwand­ten Fähig­kei­ten der Soft­ware, die mit dem Bau­stein Case doku­men­tiert wer­den.

Bau­stein Case

Der Bau­stein Case gibt einem Anwen­dungs­­fall, einer beson­deren Situat­ion oder einem bekann­ten und akzep­tier­ten Feh­ler einen ein­deu­tigen Namen und ent­hält eine fach­liche Beschrei­bung und — sobald die Fähig­keit reali­siert wurde — die Essenz­schritte der gewähl­ten Lösung.

Zurück zur Über­sicht.


Lösungs­raum

Bau­steine der System­struk­tur

Unter dem Sammel­begriff System­struktur bündelt cards+ Bau­steine für Dienste und Objekte. Sie haben das Ziel, die Struk­tur der Soft­ware zu erfassen und einen Über­blick über das Zusam­men­spiel von Diensten und Objekten zu geben.

Software architecture is loosely defined as the organi­zational structure of a software system including compo­nents, connec­tions, constraints and rationale.

Paul Clement

Was Paul Clement hier beschreibt, ist ein wesent­licher Trei­ber für die Bau­steine der System­struk­tur. Auch die Idee des “domain driven design” wird in cards+ berück­sich­tigt und spie­gelt sich in Bezeich­nung der Bau­steine. Das Ziel der gemein­samen Sprache ver­folgen beide Ansätze.

Ein Punkt ist beson­ders wich­tig: Ent­wick­ler brauchen keine Doku­men­tation, die im Detail erklärt, wie Code funktio­niert.

Nur im Code steckt die volle Wahr­heit! Das ist eine Tat­sache, die Autoren akzep­tieren und zu ihrem Vor­teil ver­wen­den, indem sie les­bare Teile vom Code, Code-Kommen­tare und code-nahe Arte­fakte als doku­men­tierte Infor­mation in die Pro­dukt­doku­men­tation auf­nehmen.

Daher gilt immer: Program­mieren ist doku­men­tieren!

Alle Details zur Imple­men­tierung befin­den sich einer Spezifi­kation. Das Wiki ist der Ort der Veröffent­lichung dieser Spezifi­kation. Die Spezifi­kation muss jedoch nicht im Wiki gepflegt wer­den.

Im Steck­brief der Bau­steine der System­struk­tur gibt es immer eine Kurz­beschrei­bung. Ganz all­gemein geht es in den Bau­steinen um die Sicherung von Wissen, das gar nicht oder nur sehr schwer aus dem Code heraus­gelesen werden kann.

Bau­stein Domain

Mit dem Bau­stein Domain geben Auto­ren einer Zusam­men­stel­lung von Diens­ten und Objek­ten mit einer star­ken Kohä­sion einen ein­deu­tigen Namen. Die unter­geor­dne­ten Bau­steine bil­den einen „bounded context“, ein Begriff aus dem Domain-Driven Design.

Bau­stein Service

Mit dem Bau­stein Service beschrei­ben Auto­ren einen fachl­ichen Dienst. Ein Dienst ist ein Akteur in einem IT-System. Ein Micro­service ist ein ein Dienst. In Storm ist eine Topo­logie ein Dienst. Ein REST-API ist ein Dienst.

Bau­stein Entity

Mit dem Bau­stein Entity beschrei­ben Auto­ren ein fach­lich rele­vantes Infor­mations­objekt. Ein Infor­mations­objekt ist ein Daten­speicher (“etwas, das exis­tiert”) oder repräsen­tiert einen Zustand in einem Dienst. Ein Infor­mations­objekt ist häu­fig mit einer Identi­tät ver­bun­den.

Bau­stein Event

Mit dem Bau­stein Event beschrei­ben Autoren ein fach­lich rele­vantes Nach­richten­objekt. Ein Nach­richten­objekt ist ein wesent­licher Bestand­teil einer event-basier­ten Schnitt­stel­le eines Diens­tes. Ein Nach­richten­objekt kann eine zeit­lich begrenzte Gültig­keit haben.

Bau­stein Layout

Der Bau­stein Layout ent­hält Ent­würfe oder Skiz­zen eines Teils der Bedien­ober­fläche. Layout ist der Ober­begriff für eine ganze Reihe speziali­sierter Aus­prägun­gen, z.B. Window und Dialog in einer Web­site oder Screen in einer Smart­phone-App. Panel, Prompt und Widget sind wieder­ver­wend­bare Layouts.

Zurück zur Über­sicht.


Lösungs­raum

Bau­steine für den Archi­tektur­ent­wurf

Der Archi­tektur­ent­wurf ist ein Sammel­begriff für Doku­mentation, mit der Autoren gefor­derte Quali­täts­merk­male, wich­tige Ent­scheidungen und über­greifende Kon­zepte beschrei­ben.

Software architecture is the set of design decisions which, if made incorrectly, may cause your project to be cancelled.

Eoin Woods

Eoin Woods sagt, dass die Archi­tek­tur allein dadurch aus­reichend genau doku­mentiert ist, wenn alle Ent­schei­dungen bekannt sind, die eine Gefahr für Pro­dukt oder Pro­jekt dar­stellen, wenn sie falsch waren. cards+ geht hier mit seinen Bau­steinen des Archi­tektur­ent­wurfs einen Schritt weiter.

Auf­trag­geber und Pro­dukt­verant­wort­liche machen Vor­gaben, die häu­fig große Aus­wirkung auf die Ent­wick­lung des Pro­duktes haben. Solche Vor­gaben werden dadurch charakteri­siert, dass sie den Lösungs­raum für die Ent­wick­lung des Pro­duktes ein­schrän­ken. Gerade bei jene Ent­schei­dungen eines Auftrag­gebers, die etwas aus­schließen, ist ein Nach­weis beson­ders wich­tig. Quali­täts­merk­male, auch bekannt als nicht funktio­nale Aspekte, legen fest, unter welchen Rahmen­bedingungen Funk­tionen eines Systems ausge­führt werden sollen. Quali­täts­merk­male werden nicht einfach programmiert. Sie sind Eigenschaften, die durch die Wahl des Archi­tektur­stils, durch den Ein­satz bestimm­ter Infra­strukur oder Anwendung bestimm­ter Ent­wurfs­muster bestimmt werden.

Bau­stein Spec für ein Kon­zept

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. Beson­deres Augen­merk liegt dabei auf den Quali­täts­merk­malen als Konse­quenz der gewähl­ten Lösung.

Bau­stein Spec für ein Modul

Mit dem Bau­stein Spec lassen sich Eigen­schaf­ten, Ein­schränkungen und Besonder­heiten von Modu­len erfassen. Modul ist ein Sammel­begriff für “fremde” Bestand­teile eines Pro­duktes. Beson­deres Augen­merk liegt dabei auf den Quali­täts­merk­malen des Moduls und die damit ver­bunde­nen nicht funktio­nalen Aspekte.

Bau­stein Decision

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.

Zurück zur Über­sicht.


Methode

Das »missing link« der Doku­menta­tion

In der System­beschrei­bung zeigt sich der Problem­raum des Pro­duktes. Dieser Teil der Doku­mentation ist das Abbild der Reali­tät, die Wirk­lich­keit aus Sicht der Nutzer des IT-Systems. Je mehr ein Team über die Welt weiß, in dem die Soft­ware einge­setzt wird, desto besser wird die Lösung.

Die tat­säch­lich reali­sierte Soft­ware beschrei­bt der Pro­dukt­verant­wort­liche in Abstim­mung mit dem Team und unter­stützt durch Ver­tre­ter des Teams mit den Bau­steinen der System­struk­tur und des Archi­tektur­entw­urfs. Bei agiler Ent­wick­lung schrei­tet die Pro­dukt­doku­men­tation im Gleich­schritt mit dem Pro­dukt voran. Das Ende einer Itera­tion ist der Zeit­punkt, an dem Pro­dukt­doku­men­tation, Code und Test­pläne eine Ein­heit bilden: Das Pro­dukt­inkre­ment.

Das »missing link« der Pro­dukt­doku­men­tation ist der Bau­stein Case. Er bildet den Über­gang der System­beschrei­bung in die System­struk­tur und umge­kehrt.

  • Ein Pro­dukt­ver­antwort­licher kann aus seiner fach­lichen Sicht ablei­ten, welche Dienste (Service) und Objekte (Event bzw. Entity) an der Lösung einer Fähig­keit der Soft­ware (Case) in der Soft­ware betei­ligt sind.
  • Ein Tester kann ein­schätzen, welche Fähig­keit der Soft­ware (Case) sich auf einen Dienst (Service) aus­wirkt, für die er Test­fälle schreibt.
  • Ein Ent­wick­ler kann den fach­lichen Kon­text (Topic, Epic und Case) eines Dienstes (Service) für sein Ver­ständ­nis heraus­finden.

Der Baustein Case hat den Abschnitt Aus­gangs­lage, in dem der Pro­dukt­ver­antwort­liche eine ein­zelne, nicht weiter teil­bare Fähig­keit der Soft­ware beschreibt. Nach Abschluss der Reali­sierung einer Fähig­keit ergän­zen er oder ein Ver­tre­ter des Teams die gewählte Lösung in Form von Essenz­schrit­ten. Diese kom­pakte Liste beschreibt die Lösung als eine Art »Pfad« durch die Soft­ware, eine Art »Navi­gation« durch die Kompo­nenten und Daten­flüsse des IT-Systems.