In dem Beitrag mit dem Titel «Shifting to Continuous Documentation as a New Approach for Code Knowledge» erklärt der Autor das Prinzip der kontinuierlichen Dokumentation. Er bezieht sich dabei auf andere Prinzipien, die in der modernen Software-Entwicklung nicht mehr wegzudenken sind. Mit Continuous Integration bauen und testen wir unsere Software kontinuierlich mit dem Ziel, früh Fehler zu entdecken (fail fast). Wir liefern unsere Software häufig mit dem Ziel, sie in kleinen gut testbaren Schritten zu verändern und nennen es Continuous Deployment. Wir liefern die Software in kurzen Abständen mit dem Ziel, auf jeden Bedarf der Kunden und Nutzer sicher und schnell zu reagieren und nennen es Continuous Delivery. Warum dokumentieren wir unserer Software nicht auch kontinuierlich und nennen es Continuous Documentation?

Continuous Documentation is the process that optimizes and reduces drift between the codebase and code-specific knowledge. Continuous Documentation applies the paradigm of automated integration of documentation into the development pipelines, by building and updating documentation incrementally, thereby keeping it in sync with the codebase. Continuous Documentation means that the Documentation is always up-to-date; Created when best and code-coupled.

— — 

InfoQ

Dokumentation ist keine Option bei der Entwicklung einer nicht trivialen Software. Sie ist notwendig, um die gewünschte Geschwindigkeit bei der Realisierung neuer Funktionen zu erreichen, ohne die Qualität der Software insgesamt zu gefährden. Sie ist wichtiges Wissen. Selbst ein sehr gut lesbarer Code kann nur erklären, wie etwas funktioniert. Wer wann was mit der Software tut kann Code alleine kaum erklären. Und Kommentare im Code sehen nur Entwickler.

Dokumentation muss korrekt sein. Dafür muss sie prüfbar sein. Kritierien sind notwendig, um entscheiden zu können, ob etwas richtig oder falsch ist.

Dokumentation muss vollständig sein. Dafür muss bekannt sein, was 100% bedeutet. Es muss ein definiertes und akzeptiertes Soll geben.

Dokumentieren ist ein kreativer Prozess. Er kann nicht komplett automatisiert werden. Ein Architekturbild muss auf den Punkt bringen, um was es geht. Es ist eine Visualisierung für das große Ganze, reduziert auf die Kernkomponenten. Eine Vision muss der Kunde verstehen. Sie muss in seiner Sprache geschrieben sein. Sie ist wichtiger Input für die Entwicklung.

Spezifizieren ist das Präzisieren von geforderten Fähigkeiten einer Software. In einem agilen Entwicklungsprozess wird inkrementell spezifiziert. Jeder Fortschritt in der Implementierung führt zu einer Veränderung in der Spezifikation. Eine Spezifikation ist eine mit dem Code eng gekoppelte Dokumentation. Aufgrund dieser Nähe muss eine Spezifikation zusammen mit dem Code versioniert werden.

Für eine Spezifikation bietet sich Asciidoc als Format an. Eine Konfigurationsdatei oder jede Schemadatei für Json, Avro, Protobuf oder XML kann mit der source-Direktive direkt als Spezifikation verwendet werden. Sauberer Code, ausgeschnitten mit der include-Direktive von Asciidoc, oder generierte Asciidoc-Fragmente werden mit einer Überschrift und einen einführenden Satz versehen zur perfekten Beschreibung. Mit Asciidoc können Tabellen gestaltet werden, mit Daten aus einer CSV-Datei, die in einem CI-Job erstellt wird. Mit der Diagramm-Erweiterung von Asciidoc wird der Text ganz einfach um Grafiken ergänzt. Text mit Visualisierungen wirkt stärker. Gute Diagramme unterstützen das überfliegende Lesen.

Dokumentation ist wichtig und sollte nicht auf später verschoben werden. Gute Dokumentation macht uns besser. Dokumentieren muss eine Aufgabe werden, die ohne zu zögern während der Entwicklung erledigt wird.