In der täglichen Projektarbeit agieren erfahrene Mitglieder in einem Entwicklungs­team oft als «Erklärbären», die komplexe fachliche oder technische Sachverhalte und architektonische Entscheidungen verständlich vermitteln.

Die Figur des Erklärbären ist eine Kunstfigur. Die Bezeichnung fand Eingang in den allgemeinen Sprachgebrauch als sprachliches Bild und beschreibt die häufige Wiederholung ausführlicher verbaler Darstellungen von Sachverhalten.

— — 

Wikipedia

In der Methode cards+ ist die Erzählung das Bindeglied, das isolierte Code-Fragmente in wertvolles, kontextualisiertes Wissen verwandelt. Die Erzählung führt wie ein roter Faden durch die Software. Die Bausteine Service, Entity und Event geben den optimalen Rahmen für die Erzählung.

In der praktischen Umsetzung wählen Erklärbären Code-Fragmente aus und ordnen sie in einer logischen Sequenz an, die für das Verständnis der Lösung entscheidend ist. So wird Wissen konserviert. Die Dokumente zeigen stets die aktuelle Lösung.

• Der Code ist das «Wie». Er zeigt die im Entwicklungs­prozess gewählte Lösung. Code ist «ausführbares Wissen». Guter Code zeichnet sich dadurch aus, dass es die Lösung so offensichtlich wie möglich darstellt.
• Der Text ist das «Warum», «Wann» oder «Wer». Hier wird das zugrunde liegende Problem erläutert. Da es oft wichtiger ist, das Problem zu erkennen als nur die Lösung zu sehen, liefert der Text den notwendigen Kontext, den der Code allein nicht vermitteln kann.

Durch diese Trennung erfüllt die schriftliche Dokumentation ihren eigentlichen Zweck: die Erläuterung des Problems sowie die Beantwortung der Fragen nach der Lösung an einer Stelle. Konsistent. Prüfbar. Durch Domain-Driven Design wird die Modellierung des Problemraums in den Vordergrund gestellt. Die Dokumentation des Problems liefert den stabilen Rahmen, während die Code-Fragmente die aktuelle Antwort auf dieses Problem zeigen.

In der praktischen Umsetzung mit «Asciidoc» nutzen die Erklärbären die include-Direktive, um die relevanten Code-Fragmente direkt in Dokumente einzubinden. Mit dieser Methode wächst die Produkt­dokumentation als integraler Bestandteil jedes Produkt­inkrements.

Wikipedia ist das wohl bekannteste 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-Entwicklungs­prozess. Ziel ist die Erstellung und Pflege einer Produkt­dokumentation in einem Wiki. Sie soll das Produkt angemessen beschreiben und dazu beitragen, die Software wandelbar und wartbar zu machen. Die Autoren­gemeinschaft setzt sich aus den Personen der Projekt­organisation 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 kundenwirksamen) 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 sie 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.
• Ein  POJO realisiert eine Persistenzklasse, die mit dem Baustein Entity dokumentiert wird. Eine Liste der Eigenschaften der Klasse ist ein guter Beleg. Kommentare im Code geben zusätzliche Hinweise.  Liquibase-Skripte sind weitere guter Belege.
• Ein Nachrichtenobjekt wird mit dem Baustein Event dokumentiert. Ein  Avro  Json oder  Protobuf-Schema ist ein guter Beleg.
• Der Baustein Case gruppiert Testfälle für eine bestimmte Fähigkeit des IT-Systems. Der lesbare Code der Testfälle ist ein Beleg sowohl für Standardfälle (engl. happy path) als auch für alle erfassten Sonderfälle und Fehlersituationen.
• Der Baustein Layout repräsentiert ein Ansicht in der Anwendung. Screenshots aus einem  Playwright-Test sind gute Belege für die aktuelle Gestaltung der Bedienoberfläche.

In der praktischen Umsetzung mit «Asciidoc» können mit der include-Direktive beliebige Fragmente des Codes in die Dokumentation eingebunden werden. Die Liste der Beispiele kann daher beliebig fortgesetzt werden. Nur die Relevanz für das Verständnis spielt eine Rolle, nicht das Format. Lesbarer, sauberer Code jeder Art ist ein wertvoller Beleg.

Mit der Veröffentlichung im Wiki kann der Code auch von Personen gelesen werden, die keine Entwickler sind. Das erweitert den Kreis der Personen, die Feedback geben können.

Im Rahmen der Methode cards+ ist «Clean code» keine rein technische Notwendigkeit, sondern die fundamentale Voraussetzung für eine gelungene Dokumentation. «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 Personen gelesen werden, die keine Entwickler sind. Damit erfüllt sauberer Code alle Voraussetzungen, um als Beleg für die Produkt­dokumentation verwendet zu werden.