STRUKTUR


Struk­tur

cards+ für Ord­nung mit System

Viele Teams star­ten mit der Ab­sicht, ihre Soft­ware zu doku­men­tie­ren. Anfangs sind Ent­wick­ler moti­viert, ihr Wis­sen auch schrift­lich zu tei­len. Ein Wiki macht es den Auto­ren auch sehr ein­fach. Ohne Regeln schrei­ben, forma­tie­ren und glie­dern sie ihre Bei­träge unter­schied­lich. Die Fol­ge ist, dass Leser Infor­matio­nen nicht auf den ers­ten Blick fin­den.

Tech­nische Redak­teure ken­nen die Prob­leme. Und sie haben auch Lösun­gen. Tech­nische Doku­men­tation ent­steht in einem Team. Doku­men­tierte Infor­matio­nen wer­den klas­sifi­ziert. Die Doku­men­tation ist hierar­chisch auf­gebaut. Doku­mente sind mit­einan­der ver­knüpft.

cards+ hilft bei der Ein­füh­rung und Durch­set­zung einer Struk­tur im Wiki. Die Lösun­gen der tech­nischen Redak­teure machen Inhalte in einem Wiki be­herrsch­bar.

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 Gegen­stand (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­zesses, 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 später jeder­zeit einen sehr kom­pak­ten Über­blick über den Um­fang des Pro­duk­tes ver­schaf­fen.

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 und nimmt 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.

Bau­stein File

Der Bau­stein File reali­siert das Kon­zept der Medien­­biblio­­thek. Mit dem Bau­stein wer­den Prä­sen­­tatio­­nen, Filme,Foto­­gra­­fien,Ab­bil­dun­­gen oder Dia­­gramme, die als Datei (engl. file) in ver­­schie­de­nen For­­matenvor­­lie­­gen, zen­­tral und ver­­link­­bar im Wiki abge­­legt.

Bau­stein Link

Der Bau­stein Link reali­siert das Kon­zept der Link­­samm­lung. Mit dem Bau­stein wird eine belie­bige Ver­knüpfung außer­halb des Wikis als doku­­men­­tierte Infor­­mation zen­­tral und ver­­link­­bar im Wiki er­fasst.

Bau­stein Term

Der Bau­stein Term reali­siert das Kon­zept für ein Glos­sar. Mit dem Bau­stein wird ein wich­tiger Begriff der Anwen­dungs­domäne, in der die Soft­­ware zum Ein­­satz kommt, zen­­tral und ver­­link­­bar im Wiki er­fasst.

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 den Namen der Bau­steine wider. Das Ziel der Eta­blie­rung einer 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. Sie 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­stei­nen um die Sicherung von Wissen, das gar nicht oder nur sehr schwer aus dem Code heraus­gelesen werden kann, als wert­volle Ergän­zung zur Spezi­fikation, die immer aus der Code-Basis stammt.

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.

Bau­stein Policy

Der Bau­stein Policy wird ver­wendet, um konse­quent alle Regeln für die Zu­sam­men­arbeit und den Ein­satz von An­wendun­gen und Werk­zeu­gen zu doku­men­tie­ren. Regeln sind Aus­druck der Qua­litäts­poli­tik in der Orga­nisation.

Zurück zur Über­sicht.


Quali­tät

cards+ hat prüf­bare 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.


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.


Struktur

Das Meta­modell der Bau­steine

Das Meta­modell der Bau­steine einer Pro­dukt­doku­mentation rich­tet sich an jene Per­sonen, die ein abstrak­tes Modell für das Ver­ständ­nis der Zusam­men­hänge brau­chen. Das Meta­modell soll eine Orien­tierung für den Ein­satz von cards+ und der effek­tiven Ver­wendung der Bau­steine im Wiki sein.

Die Bau­steine der System­struk­tur orien­tie­ren sich auch an Kon­zep­ten, die Eric Evans in sei­nem Buch »Domain-Driven Design: Tack­ling Com­plexity in the Heart of Soft­ware« sehr aus­führ­lich beschreibt. Das gilt im Beson­de­ren für die gemein­same Sprache (engl. ubiqui­tous language) und der Fest­legung von Kon­text­gren­zen (engl. bounded con­text). Die gemein­same Sprache fin­det bei cards+ Aus­druck durch das Glossar und die konse­quente Ver­wen­dung der Sei­ten­titel der Bau­steine im Wiki ent­spre­chend dem Prin­zip COD. Kon­text­grenzen werden in den Bau­steinen Domain (Grup­pie­rung eng ver­wandter Dienste und Objekte) und Service (z.B. für die Grup­pie­rung der Micro­services eines Dienstes) defi­niert.

Ver­ein­fach­tes Meta­modell

Die Bau­steine der System­beschrei­bung sind streng hierar­chisch struk­turiert und unters­tützen so die Arbeits­weise top down bei der Ana­lyse. Das bedeu­tet, dass ein Autor die Gren­zen der Soft­ware im Bau­stein Topic beschreibt. In seiner weiteren Ana­lyse der Fähig­keiten der Soft­ware gibt er im Bau­stein Epic einen Über­blick. Den Bau­stein Case nutzt er, um jede einzelne Fähig­keit der Soft­ware zu erfassen und mit den Essenz­schritten in der Lösung den Über­gang zu den Bau­steinen der System­struk­tur zu schaffen.

Die Bau­steine der System­struk­tur haben das Ziel, die Struk­tur der Soft­ware abzu­bilden. Abhän­gig vom Archi­tektur­stil erge­ben sich durch den Bau­stein Domain Grup­pen von Diensten (Bau­stein Service) und Objekten (Bau­steine Event bzw. Entity). Der Bau­stein Task ist Platz­halter für Hand­lungs­anweisung, die eine Betriebs­organi­sation braucht, um einen unter­bre­chungs­losen und stö­rungs­freien Betrieb des IT-Systems zu gewähr­leis­ten.

Die Bau­steine für den Archi­tektur­ent­wurf schaf­fen einen Rah­men für funda­men­tale Ent­scheidun­gen, Kon­zep­te und Richt­linien. Die Bau­steine Decision Und Spec haben die Auf­gabe, den Archi­tektur­stil nach­voll­zieh­bar zu beschrei­ben. Das ist ein wich­tiges Ele­ment der Kommuni­kation im Team und mit allen inter­essier­ten Par­teien. Mit dem Bau­stein Policy bekom­men Richt­linien einen fes­ten Platz in der Pro­dukt­doku­men­tation.


Struk­tur

Dienste mit REST-API

In diesem Archi­tektur­stil besteht das IT-System aus einer Menge von Diens­ten, die eine Abfrage­schnitt­stelle (engl. query interface) mit einem REST-API anbie­ten. In diesem Archi­tektur­stil besteht eine starke Lauf­zeit­kopp­lung zwischen den Diensten und eine starke Abhängig­keit durch gemeins­am genutzte Infor­mations­objekte.

Es gilt die Prä­misse, dass ein Dienst eine kon­krete Funktio­nali­tät reali­siert, die durch den Bau­stein Epic fach­lich begrenzt wird. Die Imple­men­tierung der REST-API wird durch den Bau­stein Spec kon­kreti­siert. Die Frei­heits­grade bei der Techno­logie­wahl inner­halb eines Dienstes werden durch Ent­schei­dungen im Bau­sein Decision beschränkt.

Jeder Dienst wird mit dem Bau­stein Service im Wiki doku­men­tiert. Als Spezifi­kation bie­tet sich die Ver­öffent­lichung mit OpenAPI oder RAML an.

Jedes an der Schnittstelle relevante Infor­mations­objekt wird mit dem Bau­stein Entity im Wiki doku­mentiert. Die Spezifi­kation der Infor­mations­objekte für das REST-API ist in der Regel bereits in der Spezifi­kation des REST-API ent­halten. Der Bau­stein Entity beschränkt sich in seinem Inhalt daher auf die Ver­mitt­lung von Wissen, das für ein tieferes, über die reine Struk­tur hinaus­gehen­des Ver­ständ­nis not­wen­dig ist.

Ein Kompo­nenten­über­blick im Wiki nutzt die Bau­steine Service und Entity für eine visu­elle Dar­stel­lung und macht ihre Zusam­men­hänge und Daten­flüsse sicht­bar.


Struk­tur

Dienst mit asyn­chro­nen Nach­richten

In diesem Archi­tektur­stil besteht das IT-System aus einer Menge von Diens­ten, die Daten event-basiert ver­arbei­ten (engl. streaming) und über Nach­richten­kanäle asyn­chron ver­teilen (engl. broadcast). In diesem Archi­tektur­stil besteht eine schwache Lauf­zeit­kopp­lung zwischen den Diensten. Die Abhängig­keit durch gemein­sam genutzte Nach­richten­objekte kann mit dem Einsatz einer Schema­evolution redu­ziert werden.

Es gilt die Prä­misse, dass ein Dienst eine kon­krete Funktio­nali­tät reali­siert, die durch den Bau­stein Epic fach­lich begrenzt wird. Die Imple­men­tierung der Nach­richten­kanäle wird durch den Bau­stein Spec kon­kreti­siert. Die Frei­heits­grade bei der Techno­logie­wahl inner­halb des Dienstes werden durch Ent­schei­dungen im Bau­sein Decision beschränkt.

Jeder Dienst wird mit dem Bau­stein Service im Wiki doku­men­tiert. Für die Spezifi­kation bie­tet sich der Ein­satz von Asciidoc an.

Jedes an der Schnitt­stel­le rele­vante Nach­richten­objekt wird mit dem Bau­stein Event im Wiki doku­mentiert. Für die Spezifi­kation eines Nach­richten­objek­tes bietet sich die Ver­wen­dung von Avro an. Der Bau­stein Event beschränkt sich in seinem Inhalt nur mehr auf die Ver­mitt­lung von Wissen, das für ein tieferes, über die reine Struk­tur hinaus­gehen­des Ver­ständ­nis not­wen­dig ist.

Ein Kompo­nenten­über­blick im Wiki nutzt die Bau­steine Service und Event für eine visu­elle Dar­stel­lung und macht ihre Zusam­men­hänge und Daten­flüsse sicht­bar.


Struk­tur

Dienste im Appli­kations­ser­ver