Qualität
cards+ ist Qualitätspolitik
Qualitätspolitik kennen wir aus dem Sprachgebrauch der Qualitätsmanagementnorm ISO 9001. Mit dem Begriff «Politik» tun sich viele schwer. Im Englischen spricht man von «policy», übersetzt also Strategie oder Leitlinie. Und so ist der Ansatz mit cards+ auch zu verstehen.
Agile Entwicklungsproszesse haben sich aus der Erkenntnis entwickelt, dass sich Anforderungen für ein IT-System nie so exakt spezifizieren lassen, dass kein Spielraum für Interpretationen bleibt. Die Welt dreht sich während der Realisierung weiter. Was heute eine gute Idee ist, kann morgen schon ein alter Hut sein.
cards+ hilft bei der Umsetzung der Werte und Prinzipien aus dem Manifest für agile Software-Entwicklung. Beim Thema Dokumentation ist natürlich der zweite Punkt im Manifest besonders interessant.
Wir schätzen funktionierende Software mehr als umfassende Dokumentation. Mit «wir» ist dabei die ganze Projektorganisation gemeint.
Manifest für agile Software-Entwicklung.
Das Ziel beim Einsatz von cards+ ist keine umfassende, sondern eine angemessene Produktdokumentation. Autoren im Wiki dürfen bei der Beurteilung der Angemessenheit nie vergessen, dass Wissen vor allem im Produkt selbst steckt. Wissen wird in Software transformiert. Der größte Teil des Wissens befindet sich im Code und in den Testplänen, die den Code prüfen.
Eine Produktdokumentation muss Qualitätsmerkmale wie Vollständigkeit und Richtigkeit aufweisen. Die ISO 9001 lehrt uns, dass Qualitätsmerkmale messbar sein müssen. Vollständigkeit wird messbar durch die Struktur im Wiki, mit Bausteinen, die einen festen Aufbau haben. Moderierte Kommentare geben Autoren ein Maß für die Richtigkeit der Bausteine.
cards+ ist ein Rahmen, innerhalb dessen Menschen es schaffen, eine komplexe Dokumentation inkrementell zu erstellen. Sie werden in die Lage versetzt, produktiv und kreativ Fähigkeiten der Software in möglichst hoher Qualität zu beschreiben. Bausteine, Prinzipien und Praktiken der Methode machen Autoren ihre Arbeit im Wiki so einfach wie möglich. Trotzdem kann cards+ keine Fehler verhindern. Sie werden aber sichtbar.
Qualität
cards+ schafft Ordnung
Das Wiki ist das zentrale Werkzeug für den Produktverantwortlichen. Dort gibt es eine ordentliche Struktur, die er gut kennt, mit Bausteinen, die er prüfen kann. Jeder Baustein hat seine Zielgruppen. Bei jedem Baustein ist klar, welche Fähigkeiten ein Autor haben muss.
Das Glossar bringt Ordnung in Begriffe. Es ist das Wörterbuch des Produktes. Die Begriffe sind das Vokabular der gemeinsamen Sprache. Es ist ein Mini-Lexikon, zugeschnitten auf das Produkt. Seine konsequente Nutzung bedeutet, dass Autoren Begriffe in den Texten der Bausteine mit Einträgen aus dem Glossar verknüpfen. Autoren können ihre Texte dadurch sehr kompakt gestalten, weil sie Begriffe nicht immer wieder erklären müssen.
Die Medienbibliothek schafft Ordnung in Bilder. Sie bildet einen Katalog für die Wiederverwendung von Abbildungen und Diagrammen. Es entsteht eine gemeinsame Bildsprache. Veränderungen an einem Bild werden sofort an allen Stellen sichtbar, es gibt keine zwei Versionen eines Bildes.
Die zentrale Verwaltung von externen Links in einer Linksammlung folgt der Idee der Medienbibliothek. Sie bildet einen Katalog für dokumentierte Informationen außerhalb des Wiki.
Für andere Dokumentenarten ist das Wiki ein zentrales Verzeichnis. Spezifikationen der Entwickler werden im Wiki zum Lesen veröffentlicht. Durch das Prinzip COD gibt es Brücken zu den Artefakten der Entwickler, Tester und Nutzer der Software. Mit dem Wiki gibt es einen “Ort”, an dem alle dokumentierten Informationen zentral für alle Leser erreichbar sind.
Disziplin
Gemeinsame Sprache
Jede Software hat das Ziel, Probleme innerhalb einer Domäne für ihre Nutzer zu lösen. Im Domain-Driven Design geht es nicht nur um die technische Umsetzung, sondern auch um eine bestimmte Denkweise beim Entwurf eines IT-Systems. Der Ansatz stellt die Modellierung der Fachlichkeit und die Schaffung einer domänenspezifischen Sprache in den Vordergrund. Die gemeinsame Sprache von Domänenexperten und Entwicklern ist ein wichtiges Ziel von cards+ und dem Domain-Driven Design.
Das Glossar enthält u.a. eine Sammlung von Fachbegriffen aus dem Geschäftsfeld im Unternehmen, in dem das IT-System zum Einsatz kommt. Es enthält Begriffe, die sehr häufig verwendet werden oder den Domänenexperten besonders wichtig sind. Es ist ein produktspezifisches Wörterbuch, ein Mini-Lexikon, zugeschnitten auf das Produkt. Darum ist es ein sehr wertvoller Teil der Produktdokumentation über den gesamten Lebenszyklus der Software. Ein Eintrag im Glossar ist in der natürlichen Sprache der interessierten Parteien (z.B. Nutzer) geschrieben. Er enthält Erklärungen zum Begriff in der primären Sprache des Entwicklungsprojektes. In einem internationalen Projekt nutzen Autoren das Glossar auch für die Übersetzung von Begriffen in andere Sprachen.
Wichtig ist, dass Autoren konsequent Querverweise als Verknüpfung zu Einträgen im Glossar verwenden. Auf diese Weise verschafft der Autor dem Leser einen sehr schnellen Zugriff auf weiterführende Informationen. Der Autor muss wichtige Begriffe nicht mehr im Text erläutern. Die Texte im Wiki werden sehr kompakt. Der Autor vermeidet mehrfache Beschreibungen eines Begriffes im Text. Damit reduziert er automatisch die Gefahr widersprüchlicher Beschreibungen.
Die Bausteine der Systemstruktur bilden eine wichtige Grundlage für die gemeinsame Sprache. Dienste und Objekte bekommen im Wiki durch den Seitentitel einen eindeutigen Namen. Der Name im Seitentitel schlägt eine Brücke zum Code und zu den Testplänen. Voraussetzung dafür ist, dass Entwickler konsequent die Namen in der Implementierung verwenden, wie folgende Beispiele zeigen:
- Der Baustein Domain repräsentiert eine Gitlab-Gruppe.
- Der Baustein Service beschreibt eine Spring-Boot-Anwendung.
- Der Baustein Entity wird durch ein POJO realisiert.
- Der Baustein Event wird durch ein Avro-Schema spezifiziert.
- Der Baustein Case gruppiert Testfälle eines Systemtests.
Autoren brauchen nur den Namen eines Dienstes oder ein Objektes des IT-Systems, um sowohl die Beschreibung im Wiki als auch die Implementierung im Code-Repository zu finden. Dieses Praxis stärkt außerdem die gemeinsame Sprache, weil Domänenexperten auch Begriffe der Entwickler kennen — und umgekehrt.
Qualität
Korrekte Sprache
Eine immer wiederkehrende spannende Frage ist, ob Entwickler im Code die Begriffe der Anwendungsdomäne ins Englische (ihrer lingua franca) übersetzen sollen — oder eben nicht.
Eine gute Übersetzung erfordert ein gewisses Maß an Kenntnissen der Fremdsprache. In den folgenden Beispielen wird deutlich, dass selbst dann eine Übersetzung nicht immer eindeutig ist. Für die Übersetzung des deutschen Wortes »Zugfahrt‘ gibt es zwei Möglichkeiten. Die erste, »train ride‘, ist die Zugfahrt eines Reisenden. Die zweite, »train run‘, ist die betriebliche Sicht auf eine Zugfahrt. Das Englische kennt keine Unterscheidung zwischen dem Halt (d.h. der Tatsache, dass ein Fahrzeug an einem Ort geplant stehenbleibt) und der Haltestelle (d.h. einem Ort, an dem solche Halte stattfinden können). Beides heißt »stop‘. Es gibt sogar Begriffe im Deutschen, für die es keine Übersetzung gibt. »Verkehrstageschlüssel« kann nicht übersetzt werden. Diese numerische Kodierung kennt außerhalb Deutschlands kaum jemand.
Entscheidet sich der Produktverantwortliche und
das Team gegen eine pauschale Übersetzung, dann kann das
Glossar
als Sperrliste für nicht übersetzbare Begriffe
verwendet werden. Die Regel ist einfach: Kein Begriff
aus dem Glossar wird im Code übersetzt. Die Folge dieser
Entscheidung ist natürlich Code in einem
Sprachenmix aus deutschen Begriffen ohne Plural
mit englischen Verben (z.B.
find
) und Stereotypen (z.B.
Repository
).
Sehr vorteilhaft in diesem Zusammenhang ist die
Vermeidung der Pluralbildung. Ein praktische
Lösung basiert auf der Verwendung des Präfix all
in
allen Fällen, wo Entwickler im Code einen Bezeichner
für eine Menge brauchen.
Bitte hier Klicken, um den Quelltext anzuzeigen
interface ZugfahrtRepository { Optional<Zugfahrt> findZugfahrtById(String id); List<Zugfahrt> findAllZugfahrt(); }
Ein weiterer Vorteil dieser Praxis entsteht bei Worten, deren Plural sich nicht vom Singular unterscheidet (z.B. das englische Wort »information« oder das deutsche Wort »Wasser«) oder bei denen der Plural eine andere Bedeutung hat (z.B. die deutschen Worte »Geld« bzw. »Gelder«). Dieser Vorteil ist sogar unabhängig von der Sprache im Code.
Es gibt aber Entwickler, die sich Code nur in Englisch vorstellen können. Sie finden deutsche Klassennamen unzumutbar, grausam, inkorrekt. Andere Entwickler schätzen jedoch die Sicherheit bei der Verwendung der Begriffe in ihrer Muttersprache, eingebettet in Code. Das ist lesbarer Code, den sie ohne Nachdenken oder Wörterbuch sofort verstehen.
Dieser Konflikt kann nur im Team geklärt werden. Ein Produktverantwortlicher muss sich jedoch immer klar machen, dass eine Übersetzung der Begriffe einer nicht englischen Domänensprache in englische Begriffe im Code entgegen dem Wunsch einer gemeinsamen Sprache von Domänenexprten und Entwickler ist.
Qualität braucht Kompetenz und Disziplin.
Kompetenz
Qualität ist Kopfsache
Eine Produktdokumentation wird gebraucht, solange das Produkt eingesetzt wird. Ist ein Produkt erfolgreich, dann sind das möglicherweise Jahrzehnte. In langen Zeiträumen ändert sich alles. Die Projektorganisation. Die Auftraggeber. Die Nutzer. Je reifer ein Produkt ist, desto wichtiger wird eine einfach zu pflegende, vollständige und vor allem richtige Produktdokumentation.
Produktwissen wächst oder ändert sich laufend in einem agilen Umfeld. Es geht um die Frage der Qualität von Dokumenten, die schon länger existieren. Sie sind von vielen kleinen Änderungen betroffen. Produktdokumentation und Produkt dürfen sich aber nicht widersprechen. Können Autoren das nicht sicherstellen, dann verdirbt ein Teil der Dokumente. Das Schlimme an «verdorbenen» Dokumenten ist, dass Leser die «faulen Stellen» selten sofort erkennen. Verdorbene Dokumente führen ein Team, das an der Entwicklung des Produktes arbeitet, in die Irre. Leider gibt es kein Werkzeug, mit dem Autoren die Qualität von Dokumenten bewerten können, so wie Entwickler beispielsweise mit SonarQube die Qualität von Software in mehreren Dimensionen messen können. Moderierten Kommentaren sind eine einfache Metrik für eine Seite im Wiki. Die Seitenvorlagen als Prototyp für eine Seite sorgt für einen einheitlichen, formal prüfbaren Inhalt. Jede gemäß Seitenvorlage des Bausteins vollständige Seite ohne Kommentare ist daher eine «gute» Seite. Und das lässt sich auf eine Blick erkennen.
Qualität ist das Ergebnis der gemeinsamen Anstrengungen aller Autoren und Leser. Es ist Kopfsache.
Disziplin
Qualität durch Beschränkung
Jede Person in der IT-Branche hat seine eigene Vorstellung von guter Dokumentation. Diese Vorstellung ist ganz maßgeblich von persönlichen Schwerpunkten oder seiner Rolle bestimmt. Auch bei der Wahl des »richtigen« Werkzeugs zum Schreiben der Dokumentation gibt es unterschiedliche Vorlieben.
- Ein Produktverantwortlicher nutzt Office-Produkte oder ein Wiki (z.B. Confluence).
- Entwickler nutze gerne Markup-Dateien, weil die sich wie Code verhalten.
- Tester denken in Tabellen oder Listen und nutzen Office-Produkte (z.B. Excel) oder spezielle Werkzeuge (z.B. Fitnesse).
- Administratoren schätzen Betriebsanweisungen und Handbücher online in einer Wissensdatenbank.
»Viele Köche verderben den Brei« ist ein Sprichwort, das wahr wird, wenn jede an der Produktentwicklung beteiligte Person »seinen« Teil der Produktdokumentation so schreibt, wie sie nach persönlichen Gesichtspunkten für richtig hält. Der Einsatz von cards+ und die Einführung eines Wiki als zentralen Ort für die Produktdokumentation ändert die Situation. Der Produktverantwortliche und das Team arbeiten mit Werkzeugen, die optimal aufeinander abgestimmt sind. Eine Grundregel bei cards+ lautet daher: Ein Autor erfasst nur Inhalte im Wiki, für die er einen passenden Baustein findet.
Entwickler schreiben Spezifikationen für Dienste und Objekte mit den gleichen Werkzeugen, mit den sie auch programmieren. Tester erarbeiten ihre Testpläne in ihrem gewohnten Werkzeugen. Die Spezifikationen und Testpläne werden nach ihrer Freigabe für das Produktinkrement vom Team zum Lesen im Wiki veröffentlicht. Es liegt in der Verantwortung des Teams, ein geeignetes Format zu wählen, das im Wiki direkt nutzbar ist oder leicht für die Verwendung im Wiki konvertiert werden kann.
Qualität entsteht durch Beschränkung der Vielfalt durch klare Regeln. Regeln, auf deren Einhaltung der Gärtner achtet.
Disziplin
Qualität durch Simplizität
Das Prinzip PLA ist eine goldene Regel in der Software-Ergonomie, Mensch-Computer-Interaktion und dem UX-Design. Das Prinzip lässt sich gut auf Dokumentation übertragen. Jeder Leser wünscht sich Informationen so aufbereitet, dass er sie gut aufnehmen kann. Im Wiki findet er eine Dokumentation mit einer nachvollziehbaren Struktur. In den Bausteinen findet er genau die dokumentierten Informationen, die er dort erwartet. Er kann gezielt den Verknüpfungen zwischen den Bausteinen folgen oder einfach suchen. Er kann jederzeit Feedback als Kommentar abgeben.
Ein einfach zu bedienendes Wiki bringt mehr Qualität durch Zusammenarbeit. Nur ein Wiki mit einfacher Struktur und verständlichen Inhalten erreicht auf Dauer alle Leser.
Kompetenz
Feedback durch Provokation
In der Software-Entwicklung arbeiten Menschen sehr intensiv zusammen. Über kurz oder lang entstehen in jedem Team Konflikte. Provozierte Konflikte sollten allerdings die Ausnahme sein. Provokation ist sehr häufig negativ belegt. Eine Provokation ist dann erfolgreich, wenn der Provozierte zu einer Reaktion genötigt wurde.
Wird ein Leser im Wiki durch den Autor mit dem Wissen anderer konfrontiert, dann kann der Leser aufgrund seines eigenen Wissens Fehler oder Lücken identifizieren. Im Wiki gibt er Feedback dazu. Ganz entspannt als Kommentar, aber trotzdem für alle anderen sichtbar. Die notwendigen Voraussetzungen für so eine positiv wirkende Provokation sind schnell aufgezählt:
- Jeder kennt die Dokumentation und ihre Struktur.
- Die Dokumentation wird von allen verwendet.
- Die Dokumentation wird von allen verbessert.
Mit dem Einsatz von cards+ erfüllen Autoren die Voraussetzung für Punkt 1 der Liste. Die Bausteine und die fixe Seitenstruktur stellen sicher, dass jeder weiß, wo wichtige Informationen zu finden sind. Mit Verknüpfungen in den Seiten führt der Autor seine Leser durch die Dokumentation. Die Suchfunktion erlaubt flexible Recherchen. Die konsequente Nutzung von Schlagworten in den Seiten macht Zusammenhänge mit einem Klick sichtbar. Punkt 2 der Liste ist Teil der Kultur der Projektorganisation. Das Wiki ist ein akzeptiertes Werkzeug für Kommunikation im Team. Ganz wichtig ist, dass die Produktdokumentation als Wahrheit gilt. Eine klare Abgrenzung zur Projektdokumentation ist wichtig. Mit Punkt 3 der Liste ist der Prozess für kontinuierliche Verbesserung gemeint.
Vollständigkeit ist keine Voraussetzung, die wollen Autoren neben Korrektheit durch das provozierte Feedback bei den Lesern erreichen. Die Idee von “collective code ownership”, wie sie beispielsweise Martin Fowler in seinem Bliki beschreibt, lässt sich leicht auf eine Produktdokumentation erweitern. Jeder ist Autor und veröffentlicht sein Wissen im Wiki. Jeder ist Leser und profitiert vom Wissen Anderer.
Die Qualität der Inhalte ist das Ergebnis der Gemeinschaft, getrieben durch Feedback. Keinen Leser lässt es kalt, wenn in »seiner« Produktdokumentation ein offensichtlicher Fehler steckt.
Disziplin
Feedback einfach so
Eine richtige Dokumentation ist immer eine große Herausforderung. Autoren im Wiki stellen sich dieser Herausforderung als Gemeinschaft und nutzen das Feedback aller Leser. Feedback einfach so zu geben, ohne extra aufgefordert zu werden, muss darum Teil der Kultur in einer Projektorganisation sein.
Richtigkeit ist ein Ergebnis kontinuierlicher Verbesserung, getrieben vom Feedback aller Beteiligten, motiviert durch den sehr gerne zitierten Grundsatz für Retrospektiven, der sogenannten obersten Direktive (engl. prime directive).
Unabhängig davon was wir entdecken werden, verstehen und glauben wir aufrichtig, dass in der gegebenen Situation, mit dem verfügbaren Wissen und Ressourcen und unseren individuellen Fähigkeiten, jeder sein bestes getan hat.
Norman L. Kerth
Mit anderen Worten: Auch Autoren machen Fehler. Und das dürfen sie auch. Es muss aber ein natürlicher Reflex jedes Lesers sein, einen Kommentar im Wiki zu hinterlassen, wenn er einen Fehler entdeckt. Jeder Entwickler kennt einen Teil des IT-Systems sehr gut. Hat er Kenntnis von einer Fähigkeit in der Software, die im Wiki nicht zu finden ist, dann gibt er den Autoren mit seinem Kommentar einen wichtigen Hinweis. Entwickler versetzen mit ihrem Feedback Autoren in die Lage, Lücken schnell schließen.
Kontinuierlicher Verbesserung ist Verbesserung in kleinen Schritten. Die Initiative der «clean code developer» formuliert dieses stete Bemühen als Pfadfinderregel.
Jede Beschäftigung mit einem Gegenstand macht ihn zumindest ein klein wenig besser. Ganz ohne bürokratische Planung.
clean code developer
Diese im Grunde genommen sehr einfache Regel verhindert, dass das Wiki an Akzeptanz verliert, weil in den Seiten Lücken und kleine Fehler enthalten sind. Wir kennen das Phänomen auch als Theorie der zerbrochenen Fenster.
Wird eine zerbrochene Fensterscheibe nicht schnell repariert, sind im Haus bald alle Scheiben zerbrochen.
James Q. Wilson und George L. Kelling
Nach ihr beginnt der Verfall von Qualität im allgemeinen Sinn mit Kleinigkeiten, die nur lange genug unbeachtet bleiben. Darum ist es essentiell, dass jeder Leser weiß, dass seine Mitarbeit wichtig ist. Autoren sind aufgefordert, wertschätzend mit diesem so wertvollen Feedback umzugehen.
Kompetenz
Feedback für den Produktverantwortlichen
Software-Entwicklung ist ganz abstrakt formuliert die Transformation von Wissen in Code. Die Bausteine Topic, Epic und die Ausgangslage im Baustein Case kann der Produktverantwortliche bereits im Backlog-Management nutzen, um Wissen nachhaltig zu erfassen. Ein Team braucht sehr detailreiches Wissen, um eine geforderte Fähigkeit der Software korrekt und vollständig zu verstehen. Dieser Bedarf geht darüber hinaus, was nach dem Prinzip KISS sinnvoll in den Bausteinen erfasst werden kann. Der Produktverantwortliche nutzt darum eine Story, um diese Wissenslücke am Beginn der Iteration zu schließen.
Eine Story im Backlog ist — ganz banal gesprochen — das Versprechen, miteinander zu reden.
Die Story verknüpft er mit dem Baustein Case. Mit dem Akzeptanzkriterien in der Story formuliert er seine Erwartung an die Lösung. Er beantwortet die Fragen der Entwickler. Gleichzeitig sind diese Fragen auch Hinweise, wo ggfs. die Texte in den Bausteinen verbessert werden sollten.
Im nächsten Schritt prüft das Team die Story hinsichtlich Vollständigkeit und schätzt die Komplexität. In der Analyse der Story (engl. refinement) reduziert das Team jede komplexe Aufgabe in eine Reihe komplizierter, manchmal sogar offensichtlicher Teilaufgaben. Eine offensichtliche Teilaufgabe hat eine wiederkehrende Lösung. Für eine komplizierte Teilaufgabe muss das Team wenigstens eine schätzbare Lösungsidee entwerfen. Damit wird jede komplexe Aufgabe beherrschbar.
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 geforderte Fähigkeit, wie sie im Baustein Case in der Ausgangslage beschrieben wird, eine passende Lösung in der Software zu finden. Die Ergebnisse des agilen Entwicklungsprozesses katalogisieren sie mit den Bausteinen der Systemstruktur und aktualisieren die Spezifikationen in den Bausteinen Service und Event bzw. Entity. Auf dem Weg der Lösungsfindung für eine komplexe Aufgabe treffen sie ggfs. noch technische Entscheidungen, die sie mit dem Baustein Decision begründen und erarbeiten Realisierungskonzepte, die sie mit dem Baustein Spec beschreiben. Als Abschluss ergänzen sie die Essenzschritte im Baustein Case mit Bezug auf die Bausteine der Systemstruktur. Die Tester erweitern ihre Testfälle in der Testpyramide zum Nachweis für die Erfüllung der Akzeptanzkriterien in der Story.
An diesem Punkt — in der Regel am Ende der Iteration — schließt sich der Kreis. Das Produktinkrement ist fertig. Der Produktverantwortliche kann nun selbst prüfen, ob seine Erwartungen, die er in der Story formuliert hat, durch die Lösung vom Team erfüllt wurden. Das bedeutet bezogen auf die Produktdokumentation, dass in mindestens einem Baustein Service die im Wiki veröffentlichte Spezifikation geändert wurde. Sie enthält nun die für die Realisierung der neuen Fähigkeit ergänzten oder geänderten Geschäftsregeln oder Algorithmen. Haben sich Datenstrukturen geändert, dann gibt es Änderungen in den Spezifikationen der Bausteine Event bzw. Entity. Die veröffentlichten Testpläne enthalten zusätzliche Testfälle, passend zu den Akzeptanzkriterien in der Story.
Der Produktverantwortliche hat immer die Möglichkeit, die Ergebnisse aus dem agilen Entwicklungsprozess direkt im Wiki nachzulesen. Die Entwickler müssen dafür nur sorgfältig die kleinen Korrekturen an den Spezifikationen gleichzeitig mit den Änderungen am Code machen. Sie tun das aber nicht für den Produktverantwortlichen. Sie profitieren selbst davon. Das kann man ohne Einschränkung als Win-Win-Situation bezeichnen.
Die Veröffentlichung im Wiki läßt sich automatisieren. Ihr Auslöser ist die Freigabe des Produktinkrements. Ein Bonus moderner Software-Entwicklung.
Kompetenz
Qualitätsmerkmale
Für die Beurteilung der Qualität von Software gibt es Qualitätsmerkmale. Die Qualitätsmanagementnorm ISO 25010 macht Vorschläge für die Kategorisierung von Qualitätsmerkmalen. Eine vollständige und korrekte Produktdokumentation ist bereits ein nicht zu unterschätzendes Qualitätsmerkmal einer Software in Bezug auf die Kategorie Wartbarkeit. Mit anderen Worten unterstützt ein Wiki mit Bausteinen der Methode cards+ die Erfüllung von Qualitätsmerkmalen der Kategorien Funktionalität und Wartbarkeit.
Mit dem Baustein Decision begründet der Produktverantwortliche oder Vertreter des Teams eine wichtige Entscheidungen, die große Auswirkung auf die Software hat oder den Lösungsraum einschränkt. Jede Entscheidung wird mindestens einem Qualitätsmerkmal zugeordnet, mit einer Begründung, die erklärt, warum sie für dieses Qualitätsmerkmal relevant ist. In der Produktdokumentation gibt es zu jedem Qualitätsmerkmal mindestens eine Entscheidung oder ein Konzept mit einer Aussage, wie und in welchem Umfang das Qualitätsmerkmal in der Software umgesetzt wurde.
Mit dem Baustein Spec dokumentieren Entwickler übergreifende oder wiederholt eingesetzte Konzepte, die u.a. sicherstellen, dass eine Software bestimmte Qualitätsmerkmale aufweist.
Bitte hier Klicken, um das Fallbeispiel anzuzeigen
Wartbarkeit
Analysierbarkeit
Die Decision Begriffe der Domäne im Code sorgt dafür, dass sich eine gemeinsame Sprache aus den Begriffen der Domäne entwickeln kann. Lesbarer Code ist das Ziel.
Die Decision Programmiersprache für Individualentwicklung legt eine Standardprogrammiersprache fest. Eine Abweichung muss gut begründet sein und darf nicht aus einer “Laune heraus passieren”.
Gemäß Spec Event-basierte Messpunkte kann jeder Dienst zur Laufzeit sogenannte Messpunkte in besondere Situationen erzeugen. Ein Messpunkt ist eindeutig identifizierbar, dokumentiert Zeitpunkt und Zuordnung zu einem Dienst, beschreibt die Situation (z.B. ein Datensatz kann nicht verarbeitet werden) und enthält alle Daten, die für eine spätere die Analyse notwendig sind.
Modularität
Der gewählte Architekturstil pipes and filters basiert auf folgenden Grundkonzepten für Dienste:
- Spec Grundkonzept für Loader-Dienste
- Spec Grundkonzept für Builder-Dienste
- Spec Grundkonzept für Manager-Dienste
Es gibt zwei Lösungsansätze für Schnittstellen von Diensten:
- Spec Event-basierte Schnittstelle mit Kafka, Avro und Schema-Registry
- Spec REST-basierte Schnittstelle mit Spring Boot
Modifizierbarkeit
Die Decision Versionsverwaltung in Git legt eine nachvollziehbare Strategie für die Versionierung der Code-Basis fest.
Die Decision Continuous Integration mit Git legt den Grundstein für hohe Code-Qualität.
Prüfbarkeit
Die Decision Werkzeug für Android-UI-Tests legt den Grundstein für automatisierbare Testausführung für die Android-App.
Die Decision Werkzeug für Schnittstellentests legt den Grundstein für automatisierbare Testausführung für Dienste.
Die Decision Werkzeug für Systemtests legt den Grundstein für automatisierbare Testausführung für das IT-System.
Stabilität
Apache Kafka ist eine Plattform für ein sehr gut skalierbares verteiltes IT-Systems mit einer event-basierten Datenverarbeitung nahezu in Echtzeit. Der Einsatz von Apache Kafka als Plattform für messaging hat sich im Laborversuch bewährt.
Apache Cassandra ist ein Vertreter der spaltenorientierten Datenbanken, der sich bei großen Datenmengen mit hoher Skalierbarkeit anbietet. Der Einsatz von Apache Cassandra als verteilte Datenbank hat sich im Laborversuch bewährt.
Der Einsatz von Spring Boot als Grundgerüst für jeden Dienst sorgt für ein einheitliches und nachvollziehbares Verhalten bei der Datenverarbeitung.
Der Einsatz von Apache Kafka Streams ermöglicht eine leichtgewichtige Lösung für streaming ohne Abhängigkeiten zu anderen Diensten.
Mit diesem Vorgehen kehrt der Produktverantwortliche die weit verbreitete Praxis um, nicht funktionale Aspekte wie Fähigkeiten anzufordern. Qualitätsmerkmale werden nicht einfach programmiert. Sie sind Eigenschaften einer Software, die durch die Wahl des Architekturstils, durch den Einsatz bestimmter Infrastruktur oder Anwendung bestimmter Entwurfsmuster entstehen. Qualitätsmerkmale beeinflussen sich gegenseitig. Häufig »zerren« sie von zwei Seiten, d.h. stärkt man ein Qualitätsmerkmal, schwächt man ein anderes. In einem verteilten IT-System kann beispielsweise die Optimierung des Zeitverhaltens bei der Datenverarbeitung die Analysierbarkeit beinträchtigen. Das CAP-Theorem ist ein weiteres Beispiel für dieses Dilemma.
Das CAP-Theorem oder Brewers Theorem besagt, dass es in einem verteilten System unmöglich ist, gleichzeitig die drei Eigenschaften Konsistenz (engl. consistency), Verfügbarkeit (engl. availability) und Ausfalltoleranz (engl. partition tolerance) zu garantieren.
Eric Brewer
Ein weiterer nicht zu unterschätzender Vorteil ist der Überblick zu jedem einzelnen Qualitätsmerkmal, der sich aus der Verknüpfung der Bausteine Decision und Spec mit dem Qualitätsmerkmal ableiten läßt. Diese kompakte Zusammenstellung von Entscheidungen und Konzepten zu einem Thema zeigt Abhängigkeiten, die sonst nicht so leicht erkennbar sind.
Disziplin
Qualitätsmanagement
Steuerungsmaßnahmen für den Entwicklungsprozess, wie sie in der Qualitätsmanagementnorm ISO 9001 von einer Organisation gefordert werden, sind nur mit genauer Kenntnis der Entwicklungsergebnisse möglich. Der Einsatz von cards+ und dem damit verbundenen Vorhaben, eine angemessene und mit der entwickelten Software wachsende Produktdokumentation zu erstellen und zu pflegen, eröffnet eine Reihe von Möglichkeiten zur Verifizierung der Entwicklungsergebnisse. Eine wesentliche Eigenschaft von cards+ ist die fixe Struktur im Wiki, mit Bausteinen, Prinzipien und Praktiken, die optimal aufeinander abgestimmt sind.
Der Baustein Topic hilft, den Umfang (engl. scope) eines IT-Systems festzulegen und klare Grenzen für die Entwicklung zu ziehen. Alle Topics zusammen beschreiben den Projektauftrag, übersetzt in die Sprache des Produktes.
Der Baustein Case wird verwendet, um eine Fähigkeit des IT-Systems zu beschreiben. Mit dem Baustein Epic werden eng verwandte Fähigkeiten zu einer kompletten Funktionalität zusammengefasst. In der Sprache der Norm sind das die Entwicklungseingaben. Eine Software, die »fertig« ist, hat für jeden Case eine Lösung oder eine Begründung, warum eine Lösung nicht möglich oder notwendig ist. Auf dieser Grundlage kann der Produktverantwortliche sehr gut beurteilen, ob alle Entwicklungseingaben bei der Realisierung vom Team berücksichtigt wurden.
Das Testen einer Software hat nicht die vollständige Prüfung aller Fähigkeiten zum Ziel. Das wird in der IT-Branche heutzutage als unmögliches Vorhaben eingeschätzt. Eine Metrik wie die Testabdeckung durch Modul-, Schnittstellen- und Systemtests versetzt den Produktverantwortlichen in die Lage, Qualitätsziele für die Entwicklung zu definieren. Der Einsatz von cards+ lässt ihn auch beim Systemtest eine Qualitätsziel definieren. Jeder Case in der Systembeschreibung mit einer Lösung muss durch mindestens einen Testfall im Systemtest abgesichert werden. So ist der Beweis erbracht, dass die Software mindestens alle in der Produktdokumentation erfassten Fähigkeiten besitzt.
Feedback
Leistungsbeschreibung für den Auftraggeber
Aufgrund der noch immer fehlenden Rechtssicherheit bei Gewerken mit agiler Software-Entwicklung besteht regelmäßig der Bedarf an einem Lastenheft. Arbeiten Auftraggeber und Produktverantwortlicher konsequent mit cards+, dann besteht die Möglichkeit, die Leistungsbeschreibung für das Lastenheft zu großen Teilen aus dem Wiki zu exportieren. Der Auftraggeber schreibt das Rahmendokument und ist Co-Autor der Bausteine der Systembeschreibung.
Das Rahmendokument schreibt der Auftraggeber selbst. An die Stelle der Leistungsbeschreibung tritt jedoch ein Export der Bausteine aus dem Wiki, die mit einer eindeutigen Kennung für den Auftrag als Stichwort versehen wurden. Jeder Baustein Case beschreibt eine einzelne Fähigkeit des IT-Systems. Mit dem Baustein Epic werden verwandte Fähigkeiten gruppiert. Der Baustein Topic schließlich legt die Grenzen des Lastenheftes fest. Bei IT-Systemen mit einer Bedienoberfläche verwendet der Produktverantwortliche auch den Baustein Layout für abgestimmte Entwürfe von Fenster, Dialogen und Masken als Vorbereitung für die Entwicklung.
Mit diesem Vorgehen legen Auftraggeber und Produktverantwortliche bereits sehr früh die Grundlage für die Systembeschreibung. Während der Realisierung werden schrittweise die Lösungen mit den Bausteinen der Systemstruktur dokumentiert. Im Baustein Case werden die Essenzschritte ergänzt. Die Produktdokumentation wächst mit dem Fortschritt des Produktes. Die eindeutigen Kennung für den Auftrag als Stichwort hat den Vorteil, dass immer erkennbar ist, welche Fähigkeiten bereits im ursprünglichen Auftrag gefordert wurde und welche erst aufgrund der Erkenntnisse während der Realisierung dazu gekommen sind.
Beim Export aus dem Wiki sorgt die Einschränkung auf die Kennung des Auftrages, dass die richtigen Seiten exportiert werden. Als Format bieten sich Word oder PDF an. In beiden Formaten bleiben die Verknüpfungen innerhalb des exportierten Dokumentes erhalten.
Feedback
Schnittstellenbeschreibung für Partnersysteme
Schnittstellenbeschreibungen sind alternativlos in einer komplexen IT-Systemlandschaft mit vielen unabhängigen Partnersystemen aus verschiedenen Organisationen eines Unternehmens. Ein Produktverantwortlicher darf sich trotzdem die Frage stellen, wie umfangreich so ein Dokument sein muss. Mit cards+ ist es möglich, eine Schnittstellenbeschreibung aus einem Rahmendokument — die Startseite der Schnittstelle — und den Bausteinen der Systembeschreibung und Systemstruktur zusammenzustellen. Neben der Startseite muss der Produktverantwortliche nur eine weitere Seite je angeschlossenem IT-System im Wiki anlegen. Die Startseite legt mit ihrem Seitentitel eine eindeutige Kennung für die Schnittstelle fest, auf die auch in anderen Dokumenten referenziert werden kann. Sie ist praktisch eine Linksammlung für alle Bausteine, die relevant für die Schnittstelle sind. Die Relevanz wird ebenfalls durch die Kennung der Schnittstelle als Stichwort in den betroffenen Seiten ausgedrückt.
Die Startseite hat folgenden grundsätzlichen Aufbau:
- Im Abschnitt Referenzen werden alle angeschlossenen IT-Systeme gelistet.
- Der Abschnitt Systemkontext zeigt die Endpunkte (Service) der beteiligten IT-Systeme in einem schematischen Komponentenüberblick.
- Im Abschnitt Operationen wird jede einzelne Operation der Schnittstelle beschrieben. Neben einer kurzen Beschreibung der Operation gibt es hier Informationen zur Häufigkeit der Aufrufe, zu den Parametern und Rückgabewerten und Besonderheiten der Fehlerbehandlung.
- Der Abschnitt Beschreibung verknüpft in einer Tabelle jede Operation mit den Fähigkeiten der Software (Case) und einem Auslöser (Event) — falls es einen gibt.
- Der Abschnitt Versionierung legt eine verbindliche Strategie für die Evolution der Schnittstelle fest, mit einer Verknüpfung zum entsprechenden Konzept (Spec).
- Der Abschnitt Qualitätsmerkmale legt verbindliche Vorgaben für den Betrieb der Schnittstelle fest, mit Verknüpfungen zu entsprechenden Konzepten (Spec) und Entscheidungen (Decision)
Der Produktverantwortliche erreicht durch dieses Vorgehen ein hohes Maß an Wiederverwendung bereits existierender dokumentierter Informationen im Wiki.
- Der Endpunkt der Schnittstelle aus der Perspektive des bereitstellenden IT-Systems wird mit dem Baustein Service in der Systemstruktur dokumentiert. Die Spezifikation beantwortet alle Fragen zur Implementierung.
- Der Endpunkt der Schnittstelle aus der Perspektive jedes angeschlossene IT-Systems wird mit dem Baustein Service als Unterseite der Startseite der Schnittstelle dokumentiert. Die Spezifikation beschreibt das Verhalten des Partnersystems bezogen auf die Schnittstelle, so wie es vereinbart wurde.
- Mit dem Baustein Event werden Nachrichtenobjekte einer event-basierten Schnittstelle dokumentiert.
- Mit dem Baustein Entity werden Informationsobjekte einer batch-orientierten Schnittstelle dokumentiert.
- Der Baustein Case gibt Einblick in die Fähigkeiten der Schnittstelle.
Dieses Vorgehen verschafft den Entwickler der Projektorganisation des Partnersystems einen sehr tiefgehenden Einblick in die Realisierung der Schnittstelle. Das fördert das Verständnis von Datenstrukturen und beugt Fehlern in der Verwendung der Operationen vor. Die hohe Transparenz erhöht außerdem die Chancen, dass die »fremden« Entwickler konstruktives Feeback geben. Das ist ein nicht zu unterschätzender Vorteil, um Fehler in der Schnittstelle frühzeitig zu identifizieren.
In vielen Fällen hat die Projektorganisation der Partnersysteme keinen Zugriff auf das Wiki oder es gibt eine Vorgabe des Unternehmens, jede Schnittstellenbeschreibung revisionssicher in einem Dokumentenmanagementsystem abzulegen. Dazu wird die Startseite der Schnittstelle mit allen verknüpften Bausteinen aus dem Wiki exportiert. Beim Export aus dem Wiki sorgt die Einschränkung auf die Kennung der Schnittstelle, dass nur die für das Partnersystem interessanten Seiten exportiert werden. Als Format bieten sich Word oder PDF an. In beiden Formaten bleiben die Verknüpfungen innerhalb des exportierten Dokumentes erhalten.