Lebendige Dokumentation

Lebendige Dokumentation beschreibt einen Ansatz, der es erlaubt, stets aktuelle und bedarfsgerechte Dokumentation bereit zu stellen, und dies für die gesamte Lebenszeit eines Produkts.

Ein wichtiger Grundsatz speist sich aus dem DRY-Prinzip, das Hunt und Thomas bereits im Jahr 2000 in ihrem epochalen Buch The Pragmatic Programmer beschrieben haben: Für jedes relevante Stück Wissen in einem System sollte es stets nur eine tonangebende Quelle geben, die dieses Wissen widerspruchsfrei und verständlich einfängt. Auf das Thema Dokumentation angewandt bedeutet dies für Software unter anderem:

• Das Erstellen von Dokumentation lässt sich für weite Teile automatisieren. Anstelle der von Hand erstellten Word-Dokumente, Software-Diagrammen etc, lassen wir uns diese aus den passenden widerspruchsfreien und tonangebenden Quellen generieren.
• Wenn immer möglich, nutzen wir als Quellformat reine Textdateien (Plain Text). Sie lassen sich einfach versionieren, auf Unterschiede untersuchen und vielfältig verarbeiten; hier kommt ein weiterer Ratschlag von Hunt & Thomas ins Spiel: "Keep knowledge in plain text". 
• Spezifikation mittels Beispielen ist eine ideale Möglichkeit, Anforderungen verständlich, maschinenlesbar und automatisiert testbar festzuhalten: BDD-Szenarien beschreiben, was das System tun soll. Das Wie liegt im Quellcode.
• Folgen wir der Idee des Domain-driven Design, so bildet die allgegenwärtige Sprache eine wichtige Grundlage als aktiver Teil einer lebendigen Dokumentation: wir nutzen ihre Begriffe im Rahmen der BDD-Szenarien ebenso wie als Teil unserer Detailspezifikation im Code; dabei spielt es keine Rolle, ob wir die taktischen Muster wie Entity, Service, Value Object, Aggregate, etc. des Domain-driven Design nutzen: die Namen der fachlichen Konzepte folgen in jedem Fall der allgegenwärtigen Sprache.
• Der Code wird zu einer wichtigen Quelle für unsere Dokumentation. Er verrät uns etwas über die tatsächliche Struktur der Software, er ist die Basis für automatisiert erstellbare Metriken, er verrät uns, was das System tatsächlich tut, und er macht es möglich, Architekturverletzungen und fehlende fachliche Konzepte zu entdecken.