cards+ ist auf Neudeutsch «optionated», also eine Methode mit eigener Meinung. Das bedeutet, dass mit den empfohlenen Werkzeugen, der Struktur der Produktdokumentation und den dazu passenden Bausteine ein bestimmtes Vorgehen verbunden ist. Es soll nur das dokumentiert werden, was nicht bereits mit lesbarem Code oder als Testfall ausreichend genau beschrieben wurde.
Wikipedia ist das wohl bekanntestes Wiki der Welt. Alle Inhalte sind offen zugänglich. Eine weltweite Autorengemeinschaft arbeitet kollektiv, unentgeltlich und anonym an den Artikeln der Enzyklopädie. Autoren kontrollieren und korrigieren sich gegenseitig. Sie nutzen eine Diskussionsseite, um Verbesserungsvorschläge zu machen oder die Korrektheit bestimmter Inhalte eines Artikels öffentlich anzuzweifeln oder zu bestätigen. Erledigte Bereiche einer Diskussion werden archiviert, marginale Fragen, die nicht mehr von Interesse sind, werden entfernt.
cards+ verbindet das Wikipedia-Prinzip mit einem agilen Software-Entwicklungsprozsses. Ziel ist die Erstellung und Pflege einer Produktdokumentation in einem Wiki. Sie soll das Produkt angemessen beschreiben und dazu beitragen, die Software wandelbar und wartbar zu machen. Die Autorengemeinschaft setzt sich aus den Personen der Projektorganisation zusammen. Leser sind alle am Produkt interessierten Parteien. Autoren nutzen die Bausteine von cards+, um dem Wiki eine nachvollziehbare Struktur zu geben. Jede Seite im Wiki erklärt einen Teil des Produktes, in der Regel den kundenwirksamen Stand der Software. Der Inhalt einer Seite im Wiki wird durch Code-Fragmente belegt. Mit der Kommentarfunktion kann in jeder Seite eine Diskussion über den veröffentlichten (und damit kundenwirksame) Stand der Software geführt werden.
Die Glaubwürdigkeit der Wikipedia hängt von der Überprüfbarkeit ihrer Inhalte ab. Alle nicht-trivialen Aussagen eines Artikels müssen belegt und auf diese Weise nachprüfbar sein.
— —Wikipedia
Eine Dokumentation einer Software kann durch Code belegt werden, wie folgende Beispiele zeigen:
- Der Baustein Domain repräsentiert ein Git-Repository. Die README-Datei ist ein guter Beleg, wenn es den Aufbau beschreibt, wichtige CLI-Befehle erklärt oder andere Hinweise für Entwickler gibt.
- Der Baustein Service beschreibt eine Spring-Boot-Anwendung mit einem REST-API. Mit Spring-REST-Docs wird automatisch eine API-Dokumentation als Beleg erstellt.
- Der Baustein Entity wird durch ein POJO realisiert. Ein Liste der Eigenschaften der Klasse ist ein guter Beleg. Kommentare im Code geben zusätzliche Hinweise.
- Der Baustein Entity wird in einer Datenbank gespeichert. Liquibase-Changesets sind gute Belege für die Eigenschaften von Datenbankobjekten.
- Der Baustein Event wird durch Avro spezifiziert. Die Schema-Datei ist ein guter Beleg.
- Der Baustein Case gruppiert Testfälle eines Fähigkeit des IT-Systems. Der lesbare Code der Testfälle ist ein Beleg dafür.
- Der Baustein Layout repräsentiert ein Ansicht in der Anwendung. Screenshots aus einem Playwright-Test sind gute Belege für die Gestaltung der Bedienoberfläche.
Die Liste kann beliebig fortgsetzt werden. Lesbarer, sauberer Code jeder Art kann als Beleg verwendet werden.
Das Wiki.
Ein Erfolgsfaktor.
«Clean code» ist ein Begriff aus der Softwaretechnik, der populär wurde durch das gleichnamigen Buch von Robert C. Martin.
Als «sauber» bezeichnen Softwareentwickler in erster Linie Quellcode, aber auch Dokumente, Konzepte, Regeln und Verfahren, die intuitiv verständlich sind.
— —Wikipedia
Das Schlüsselwort ist «verständlich». Code, der intuitiv verständlich ist, kann auch von einem Nicht-Entwickler gelesen werden. Damit erfüllt sauberer Code alle Voraussetzungen, um als Beleg für die Produktdokumentation verwendet zu werden.
Mit Asciidoc(tor).
Für Qualität.
-
Agil dokumentieren, geht das?
Das Ziel agiler Entwicklung ist es, den Entwicklungsprozess flexibler und schlanker zu gestalten, als das bei den klassischen Vorgehensmodellen der Fall ist. Gilt das auch für das Dokumentieren?
Jetzt lesen -
Neustart auf „grüner Wiese“.
Nehmen Sie an, Sie werden beauftragt, ein völlig neues Software-Produkt zu entwickeln. Sie bekommen die Chance, eine individuelle Lösung mit einer agilen Projektorganisation auf der „grünen Wiese” zu entwerfen.
Jetzt lesen -
Zurück auf Anfang.
Stellen Sie sich ein Szenario vor, in dem ein Auftraggeber ein individuell entwickeltes IT-System durch eine Lösung mit einem Standardprodukt ersetzen will. Sie bekommen den Auftrag, die Migration zu planen und umzusetzen.
Jetzt lesen -
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.
Jetzt lesen -
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+ kann er das Wiki zu seinem Vorteil nutzen.
Jetzt lesen -
Gute Programmierer – schlechte Software
Ein Gerichtssachverständiger für Softwarequalität erklärt, warum Software selten dem Stand der Technik entspricht.
Jetzt lesen -
Warum nicht kontinuierlich Dokumentieren?
Mit Continuous Documentation ändern wir die Art und Weise, wie wir Spezifikationen erstellen und integriert in einer Produktdokumentation konsumieren. Wir folgen den Prinzipien der kontinuierlichen Verbesserung in den Dimensionen Code, Test und Spezifikation.
Jetzt lesen -
Ist Domain-Driven Design überbewertet?
Ist der Hype um Domain-Driven Design berechtigt oder verbirgt sich dahinter nur alter Wein in neuen Schläuchen?
Jetzt lesen