Once-Only in Dokumentationen

Was ist das Once-Only-Prinzip?

Das Once-Only-Prinzip besagt: Daten oder Informationen sollen nur einmal erfasst, gespeichert und gepflegt werden – und an allen relevanten Stellen wiederverwendet werden. Es vermeidet Redundanz, minimiert Fehlerquellen und reduziert Wartungsaufwand. Ursprünglich aus der Verwaltung und dem E-Government bekannt, gewinnt es auch in technischer Dokumentation zunehmend an Bedeutung – besonders in komplexen, agilen und skalierbaren Systemen.

Warum ist Once-Only in Dokumentationen wichtig?

In Softwareprojekten wachsen Dokumentationen oft unkoordiniert:

• API-Dokumentationen existieren separat von Benutzerhandbüchern.
• Diagramme werden manuell gezeichnet und nicht mit Code synchronisiert.
• Konfigurationshinweise werden in mehreren Dokumenten dupliziert.

Das führt zu Inkonsistenzen, veralteten Inhalten und erhöhtem Pflegeaufwand. Once-Only schafft hier Klarheit:

Einmal schreiben. Überall nutzen.

Documentation Engineering: Die Grundlage für Once-Only

Documentation Engineering ist die systematische, ingenieurmäßige Herangehensweise an Dokumentation – mit Fokus auf Struktur, Wiederverwendbarkeit und Automatisierung. Es ermöglicht:

• Modulare Dokumente: Inhalte werden in wiederverwendbare Bausteine (z. B. „Komponentenbeschreibungen“, „Fehlercodes“) zerlegt.
• Zentrale Quellen: Alle Inhalte stammen aus einer einzigen, gepflegten Quelle (Single Source of Truth).
• Automatisierte Verknüpfung: Inhalte werden dynamisch in verschiedene Ausgabeformate (PDF, Web, Help-Systeme) übersetzt.

Beispiel:
Ein API-Endpunkt wird in einer YAML-Datei beschrieben. Diese dient als Quelle für:

• Swagger/OpenAPI-Dokumentation
• Benutzerhandbuch-Abschnitte
• Entwickler-Referenz
• Automatisierte Tests

→ Keine manuelle Kopie. Keine Inkonsistenz. Nur eine Quelle.

Docs-as-Ecosystem: Dokumentation als lebendiges System

Ein Docs-as-Ecosystem versteht Dokumentation nicht als statisches Artefakt, sondern als integriertes, dynamisches System, das mit Code, Tests, CI/CD und Monitoring verbunden ist.

Merkmale eines Docs-as-Ecosystem:

• Automatische Generierung: Dokumentation wird aus Code-Kommentaren, Konfigurationsdateien oder Tests generiert.
• Feedback-Schleifen: Nutzer können direkt aus der Dokumentation Feedback geben – z. B. über „War diese Information hilfreich?“-Buttons.
• Versionierung: Dokumentation wird mit dem Code versioniert – keine Diskrepanzen zwischen Version 1.2 und der dazugehörigen Dokumentation.
• Suchbarkeit & Navigation: Inhalte sind über Suchmaschinen und intelligente Navigation verknüpft – nicht nur linear lesbar.

Wirkung auf Once-Only:
Jeder Inhalt ist Teil eines Netzwerks. Änderungen an einer Stelle wirken sich automatisch auf alle abhängigen Dokumente aus – ohne manuelle Nachpflege.

Diagrams-as-Code: Visualisierungen als Code

Diagramme sind oft die größte Quelle für Redundanz:

• Ein Architekturdiagramm wird in PowerPoint erstellt, dann in Confluence eingefügt, dann in ein PDF kopiert.
• Bei Änderungen muss es überall manuell aktualisiert werden.

Lösung: Diagrams-as-Code

Mit Tools wie Mermaid, PlantUML, Graphviz oder Diagrams.net (mit Code-Export) werden Diagramme als Text definiert – und können in die Dokumentation integriert werden.

Beispiel (Mermaid):

graph TD
    A[Benutzer] --> B[API-Gateway]
    B --> C[Auth-Service]
    B --> D[Order-Service]
    C --> E[DB]
    D --> E

→ Dieser Code kann in Markdown, Sphinx, Docusaurus oder andere Systeme eingebettet werden.
→ Änderungen am Code aktualisieren automatisch das Diagramm in allen Dokumenten.
→ Keine manuelle Pflege. Keine veralteten Grafiken.

Docs-as-Code: Die technische Umsetzung von Once-Only

Docs-as-Code ist die Praxis, Dokumentation wie Software zu behandeln:

• In Git versioniert
• Mit CI/CD automatisiert
• Mit Tests validiert
• Mit Pull Requests gepflegt

Wichtige Elemente:

• Quellcode-Repositories: Dokumentation liegt im selben Repo wie der Code – oder in einem dedizierten, aber verknüpften Repo.
• Automatisierte Builds: Bei jeder Änderung wird die Dokumentation neu generiert und veröffentlicht.
• Validierung: Links werden geprüft, Syntax wird validiert, Diagramme werden gerendert.
• Wiederverwendung: Mit Include- oder Import-Mechanismen werden Bausteine in mehreren Dokumenten wiederverwendet.

Beispiel mit Antora (AsciiDoc):

.. include::requirements.adoc

Änderungen an requirements.adoc wirken sich auf alle Dokumente aus, die sie einbinden.

Praktische Umsetzung: Schritt-für-Schritt

1. Identifiziere redundante Inhalte
   → Welche Abschnitte werden mehrfach kopiert? Welche Diagramme existieren in mehreren Versionen?

2. Erstelle zentrale Quellen
   → Fasse wiederkehrende Inhalte in wiederverwendbaren Dateien zusammen (z. B. shared/, components/).

3. Wähle Tools, die Docs-as-Code und Diagrams-as-Code unterstützen
   → Markdown + Mermaid (oder AsciiDoc + PlantUML) + Git + CI/CD (z. B. GitHub Actions, GitLab CI).

4. Integriere Dokumentation in den Entwicklungsprozess
   → Jede Codeänderung, die die API betrifft, erfordert eine Dokumentationsänderung – als Teil des Pull Requests.

5. Automatisiere Validierung und Veröffentlichung
   → Prüfe Links, Syntax, Diagramme. Veröffentliche automatisch auf einer Dokumentations-Website.

6. Etabliere Feedback-Mechanismen
   → Nutzer können direkt aus der Dokumentation Feedback geben – z. B. über GitHub Issues oder integrierte Formulare.

Fazit: Once-Only ist kein Luxus – es ist notwendig

In einer Welt, in der Software ständig wächst und sich ändert, ist manuelle Dokumentation nicht mehr tragbar. Once-Only ist die Antwort:

• Effizienz: Weniger Arbeit, weniger Fehler.
• Konsistenz: Alle Nutzer sehen denselben, aktuellen Stand.
• Skalierbarkeit: Dokumentation wächst mit dem System – ohne zusätzlichen Aufwand.

Mit Documentation Engineering, Docs-as-Ecosystem und Docs-as-Code wird Once-Only nicht nur möglich – es wird zur Grundlage einer modernen, lebendigen Dokumentation.

• ←Zurück
• Weiter→