Methode
Motivation für den Einsatz
Unabhängig vom Architekturstil verwendet jedes IT-System Informationsobjekte. Diese Objekte sind ganz allgemein Daten (“etwas, das existiert”) oder repräsentieren einen Zustand im einem Datenspeicher. Ein Informationsobjekt hat häufig eine Identität. Der Baustein Entity ist ein Artefakt der Systemstruktur, mit dem wir solche Ergebnisse der Software-Entwicklung dokumentieren. Dabei steht der fachliche Nutzen des Dienstes im Vordergrund. Der Titel des Bausteins gibt einem wichtigen Informationsobjekt einen eindeutigen Namen.
Autoren wollen im Baustein Entity nur das dokumentieren, was Entwickler nicht durch lesbare Teile vom Code oder code-nahe Artefakte bereits ausreichend gut dokumentiert haben. Mit einem Avro-Schema oder einem Json-Schema kann beispielsweise ein auf JSON basierendes Informationsobjekt spezifiziert werden. Mit einem XML-Schema spezifizieren Entwickler ein auf XML basierendes Informationsobjekt. Autoren beschreiben im Wiki nur, was sich gar nicht oder sehr schwer aus dem Code herauslesen lässt.
Wissensmanagement richtig organisieren.
Zielgerichtet.
Agil.
Iterativ.
Prozesse
Projektmanagement
Der Produktverantwortliche hat mit dem Baustein Entity die Möglichkeit, frühzeitig ein wichtiges Informationsobjekt als Entwurf zu erfassen, wenn es für das Verständnis der Anwendungsdomäne hilfreich ist. Er macht das in Abstimmung mit dem Team.
Im Steckbrief des Bausteins befindet sich eine Liste der geplanten Technologien für die Implementierung des Informationsobjektes. Das ist eine sehr wertvolle Information für das Architekturmanagement, um Themen wie Lizenzkosten, technische Unterstützung vom Hersteller oder unternehmensweite Vorgaben rechtzeitig zu behandeln.
Prozesse
Anforderungsanalyse
Der Produktverantwortliche hat mit dem Baustein Entity die Möglichkeit, alle Eigenschaften eines Informationsobjektes zu beschreiben, die wichtig für das Verständnis der Fähigkeiten der Software sind. Er macht das in Abstimmung mit dem Team.
Prozesse
Produktentwicklung
Der Baustein Entity ist für Leser (z.B. Entwickler oder Tester) der zentrale Einstieg, um sich über die Bedeutung eines Informationsobjekt und seiner Eigenschaften zu informieren. Der Überblick im Baustein muss jeden Leser in die Lage versetzen, das Objekt fachlich einzuordnen. Die Festlegung der Identität eines Informationsobjektes ist hilfreich, um eindeutige Schlüssel für Indizierung oder Partitionierung ableiten. In der im Baustein veröffentlichten Spezifikation finden Leser alle Details zur Implementierung des Informationsobjektes.
Gemäß Prinzip COD gilt der Titel des Bausteins und die Namen der beschriebenen Eigenschaften als Vorgabe für den Namen der Implementierungsklasse und die Bezeichner der Attribute eines Informationsobjektes. Mit dieser einfach umzusetzenden Regel muss kein Autor mehr eine spezielle Dokumentation im Wiki schreiben, um ein Informationsobjekt mit der technischen Lösung zu verknüpfen. Der Titel des Bausteins reicht als Einstieg in die Implementierung.
Seitenvorlagen für alle Bausteine und hilfreiche Makros für die Verwendung in Confluence.
Qualität
Seitenvorlage des Bausteins
Confluence unterstützt mit Seitenvorlagen die Idee der Bausteine optimal. Das folgende Beispiel kann direkt als HTML im Editor der Seitenvorlagen eingefügt werden.
Bitte hier Klicken, um den Quelltext anzuzeigen
<ac:layout>
<ac:layout-section ac:type="single">
<ac:layout-cell>
<h1>Steckbrief</h1>
<ac:structured-macro ac:macro-id="602764ad-f953-4c2a-9ee5-db2568da1960" ac:name="details" ac:schema-version="1">
<ac:rich-text-body>
<table class="relative-table wrapped" style="width: 100.0%;">
<colgroup> <col style="width: 25.0%;"/> <col style="width: 75.0%;"/> </colgroup>
<tbody>
<tr>
<th>Kurzbeschreibung</th>
<td>
<div class="content-wrapper">
<ac:structured-macro ac:macro-id="b3036271-d6f0-45a5-9bf3-585e13ce4a3f" ac:name="excerpt" ac:schema-version="1">
<ac:parameter ac:name="atlassian-macro-output-type">BLOCK</ac:parameter>
<ac:rich-text-body>
<p>
<ac:placeholder>Beschreibung der Herkunft und der fachlichen Bedeutung des Informationsobjektes.</ac:placeholder>
</p>
</ac:rich-text-body>
</ac:structured-macro>
</div>
</td>
</tr>
<tr>
<th colspan="1">Technologie</th>
<td colspan="1">
<ac:placeholder>Komma-separierte Liste der verwendeten Technologien. </ac:placeholder>
</td>
</tr>
</tbody>
</table>
</ac:rich-text-body>
</ac:structured-macro>
<h1>Eigenschaften</h1>
<table class="relative-table wrapped" style="width: 100.0%;">
<colgroup> <col style="width: 25.0%;"/> <col style="width: 75.0%;"/> </colgroup>
<tbody>
<tr>
<th>Name der Eigenschaft</th>
<th>Beschreibung der Eigenschaft</th>
</tr>
<tr>
<td>
<ac:placeholder>Name der Eigenschaft.</ac:placeholder>
</td>
<td>
<ac:placeholder>Beschreibung der Eigenschaft.</ac:placeholder>
</td>
</tr>
</tbody>
</table>
<h1>Identität</h1>
<p>
<ac:placeholder>Beschreibung der Identität des Informationsobjektes, d.h. wie wird das Informationsobjekt eindeutig referenziert.</ac:placeholder>
</p>
</ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="single">
<ac:layout-cell>
<p>
<br/>
</p>
</ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="single">
<ac:layout-cell>
<h1>Spezifikation</h1>
<ac:structured-macro ac:macro-id="7ee4d7d7-823e-409d-8344-a88f5af8053c" ac:name="section" ac:schema-version="1">
<ac:rich-text-body>
<ac:structured-macro ac:macro-id="f67afd15-e789-4765-b63a-7c89d7b45a79" ac:name="expand" ac:schema-version="1">
<ac:parameter ac:name="title">tbd (v1)</ac:parameter>
<ac:rich-text-body>
<p>
<ac:placeholder>Bitte hier den Link zur Unterseite mit der Spezifikation für das Informationsobjekt einfügen.</ac:placeholder>
</p>
</ac:rich-text-body>
</ac:structured-macro>
</ac:rich-text-body>
</ac:structured-macro>
</ac:layout-cell>
</ac:layout-section>
</ac:layout>
Struktur
Eigenschaften des Bausteins
Der Baustein Entity repräsentiert ein wichtiges Informationsobjekt (engl.
entity) des IT-Systems.
Er hat einen Steckbrief mit einer Kurzbeschreibung und einer Liste der
eingesetzten Technologien.
Er erklärt wichtige Eigenschaften des Informationsobjekt und definiert die
Identität des Objektes.
Der Seitentitel beginnt immer mit Entity.
Durch die Seitenvorlage hat jede Seite das Stichwort entity.
Sie kann aber um weitere Schlagworte ergänzt werden.
Dadurch wird die Seite leichter auffindbar.
Der Baustein Entity hat eine Unterseite für jede veröffentlichten Spezifikation. Erlaubt der Architekturstil mehr als eine Version des Objektes, z.B. durch Schemaevolution, dann gibt es auch mehr als eine gültige Spezifikation mit entsprechender Kennzeichnung.
Der Baustein Entity hat einen Zustand. Er ist in Arbeit, wenn keine Spezifikation vorhanden ist. Er ist fertig, wenn eine Spezifikation vorhanden ist und die Implementierung Teil eines Produktinkrementes ist.
Der Baustein Entity hat durch die Spezifikation einen Bezug zu einem Produktinkrement.
Der Baustein Entity wird in der Sprache der Entwickler geschrieben.