Effektive und effiziente Dokumentation in Softwareprojekten mit Documentation-as-a-Code
In der Welt der Softwareentwicklung ist die Dokumentation ein entscheidender Aspekt für den nachhaltigen Erfolg eines Softwareprodukts. Diese wird jedoch häufig nicht mit der erforderlichen Qualität gepflegt. Traditionell ist die Dokumentation auf verschiedene Quellen verteilt, von Code-Kommentaren bis hin zu Wiki-Seiten, was die Aufrechterhaltung von Konsistenz, Genauigkeit und Zugänglichkeit erschwert.
Eine weitere Herausforderung ist die Pflege der einmal erstellten Dokumentation. Je mehr Dokumentationsmaterial erstellt wird, desto mehr müssen diese Artefakte in regelmäßigen Abständen überarbeitet werden. Gerade in größeren Projekten kann dies schnell zu unübersichtlichen und mit der Zeit immer schwieriger wartbaren Prozessen führen, die mit der Unbrauchbarkeit der Dokumentation und im schlimmsten Fall mit der Unbrauchbarkeit von Systemkomponenten endet. Dem entstandenen (finanziellen) Schaden folgt dann meist ein intensives Reverse Engineering oder gar eine Neuentwicklung.
Mit einer Herangehensweise, bei der die Dokumentation als integraler Bestandteil des Quellcodes behandelt wird, lassen sich einige dieser Herausforderungen effektiv und effizient lösen. In diesem Blogbeitrag wird das Konzept „Documentation-as-a-Code“ im Kontext von Entwickler- und Architekturdokumentation und seine transformativen Auswirkungen auf Softwareprojekte näher betrachtet.
Dokumentation ist verteilt
Um die Herausforderungen angemessen einschätzen zu können, sollte man zunächst verstehen, wo sich in der Regel die verschiedenen Formen der Dokumentation wiederfinden. In vielen Projekten ist die Dokumentation (unfreiwillig) auf unterschiedliche Quellen verteilt, darunter:
- Code-Kommentare (z. B. KDoc oder JDoc in Kotlin/Java-Projekten)
- Wiki-Seiten (ggf. bei mehreren Unternehmen)
- Ticket-Kommentare
- E-Mails und Chats
- In den Köpfen verschiedener Teammitglieder
Inhaltsverzeichnis
Typische Anti-Patterns ohne Documentation-as-a-Code
Die herkömmliche Herangehensweise an die Dokumentation führt zu verschiedenen Herausforderungen, die im Laufe des Projektlebenszyklus zu mindestens einem der folgenden Anti-Pattern führen können:
- Fehlende Konsistenz: Dokumentation aus verschiedenen Quellen kann oft keine einheitliche Struktur aufweisen und identischen Standards entsprechen.
- Veraltete Informationen und fehlende Aktualität: Dokumentationen ohne regelmäßige Pflege können veralteten oder nicht aktuellen Anforderungen entsprechende Informationen enthalten.
- Unzureichende Versionierung von Dokumentation: Mehrere gleichzeitig veröffentlichte Versionen eines Systems werden nicht versioniert dokumentiert bzw. aufgrund der erhöhten Komplexität nicht konsequent und konsistent gepflegt.
- Zeitverschwendung und erschwerte Informationssuche: Das Sammeln von Informationen aus verschiedenen Quellen und die Suche in einem unübersichtlichen Dokumentationsumfeld sind zeitraubend und frustrierend.
- Fehleranfälligkeit: Ohne Überprüfungs- und Feedbackmechanismen besteht ein höheres Risiko von Fehlern und Ungenauigkeiten.
- Unklare Verantwortlichkeiten und schlechte Nachverfolgbarkeit: Die Identifikation von Autor:innen und Prüfer:innen ist oft undurchsichtig, ebenso wie die Nachverfolgung von Änderungen bei verteilter Dokumentation.
- Dokumentationsnutzer: Die Identifizierung der Zielgruppe ist nicht trennscharf und wird häufig vermischt.
- Vertrauenswürdigkeit und Single-Source-of-Truth: Ungepflegte und fehlerhafte Dokumentation führt zu mangelnder Vertrauenswürdigkeit und der Abwesenheit einer Single-Source-of-Truth, was die Nützlichkeit für Benutzer:innen beeinträchtigt.
Dies kann vor allem problematisch werden, wenn Projektmitglieder während oder nach dem Projekt das Team verlassen und für aufkommende Rückfragen schwierig bis unerreichbar sind.
Vorteile durch die Verwendung von Documentation-as-a-Code
Die Documentation-as-a-Code adressiert vor allem die Entwickler-, sowie Teile der Architekturdokumentation. Dabei ersetzt die Documentation-as-a-Code die traditionelle Dokumentation nicht, sondern ergänzt sie sehr sinnvoll.
Der entscheidende Vorteil der Dokumentationspflege in der Codebasis ist die versionierte Dokumentation (z.B. über den Git-Flow), in der bei gleichzeitigem Betrieb verschiedener Versionen immer die versionsrelevante Dokumentation gelesen werden kann.
Die Anforderungen an die Documentation-as-a-Code und die daraus resultierenden Vorteile adressieren die zuvor beschriebenen Herausforderungen:
- Konsistenz: Code-basierte Dokumentation gewährleistet eine einheitliche Struktur und ermöglicht einfache Aktualisierungen, um die Konsistenz aufrechtzuerhalten. Darüber hinaus können Links zu relevanten Dokumentationen mit anderen interagierenden Systemen gesetzt werden, die im besten Fall ebenfalls versioniert sind.
- Wiederverwendbarkeit: Modulare Code-Dokumentation erleichtert die Wiederverwendung von Inhalten und Abschnitten, was die Effizienz steigert. Entsprechende Templates führen zu einer Standardisierung und steigern die Lesbarkeit der Dokumentation signifikant.
- Zusammenarbeit und iterative Verbesserung: Teammitglieder können gemeinsam an der Dokumentation arbeiten, Änderungen nachverfolgen und im Pull-Request-Reviewprozess Feedback geben. Dies fördert die nachhaltige Pflege der Dokumentation. Die Instandhaltung und der Review sollten Teil der Definition of Done (DoD) sein. Gleichzeitig ermöglicht der Code eine schnelle iterative Verbesserung der Dokumentation.
- Veröffentlichung in verschiedenen Ausgabeformaten: In regelmäßigen Abständen können die Inhalte in verschiedene Ausgabeformate wie PDF- oder HTML-Seiten exportiert werden.
- Code-Integration und Automatisierung: Code-basierte Dokumentation ermöglicht die nahtlose Integration mit anderen Tools und Ressourcen sowie die Automatisierung von Aktualisierungs- und Bereitstellungsprozessen über eine CI/CD-Pipeline.
- Versionierung und Nachverfolgbarkeit: Die Dokumentation ist versioniert, Änderungen werden nachverfolgt, Fehler werden minimiert. Wenn bestimmte Features im Git-Flow zurückgesetzt werden müssen, wird die Dokumentation entsprechend reversiert.
- Skalierbarkeit: Die Dokumentation wächst mit dem Projekt und erleichtert das Hinzufügen und Aktualisieren von Abschnitten nach Bedarf.
- Einfache Darstellung von Diagrammen: Die Darstellung verschiedener Diagramme, wie Sequenz-, Klassen- oder Komponentendiagramme, kann relativ einfach umgesetzt werden.
- Technologie- und plattform-agnostisch: „Documentation-as-a-Code kann sowohl im Frontend als auch im Backend eingesetzt werden. Unabhängig von der verwendeten Technologie oder Plattform kann die Dokumentation konsistent und effizient erstellt und verwaltet werden.
- Qualitätsziele und Dokumentation-as-a-Code: Bei temporär eingesetzten externen Teams kann Dokumentation-as-a-Code als Qualitätsziel für spätere Übernahmen dienen, um das Verständnis für ein Projekt zu erhöhen und Risiken bei der Wartung und Weiterentwicklung zu minimieren.
Praktischer Einsatz mit Documentation-as-a-Code
Eine bewährte Möglichkeit Documentation-as-a-code zu realisieren, ist zum Beispiel über AsciiDoc, eine ausgereifte und leichtgewichtige Textauszeichnungssprache für die Erstellung von technischen Inhalten. AsciiDoc Inhalte können somit technologie- und plattform-agnostisch mit einem beliebigen Text Editor geschrieben werden. Eine ausführliche und leicht verständliche Dokumentation ist auf der Webseite des AsciiDoc-Projekts zu finden https://docs.asciidoctor.org/asciidoc/latest/.
Für beliebige IDEs wie IntelliJ, Android Studio oder Visual Studio Code kann das entsprechende AsciiDoc Plugin installiert werden, welches unter anderem eine Live-Preview für die geschriebene Syntax anbietet oder das Exportieren in ein anderes Ausgabeformat ermöglicht, siehe https://docs.asciidoctor.org/asciidoctor/latest/tooling/ .
Beispiel: Documentation-as-a-Code im Frontend und Backend
Exemplarische multimodulare Architektur in einer mobilen App
Um eine strukturierte Documentation-as-a-Code Routine zu etablieren, die für Entwickler:innen, Architekt:innen und sonstige Leser:innen das Onboarding in die jeweilige Komponente ermöglicht, würde man in einem mobilen multimodularen Projekt auf einer hohen Abstraktionsebene in jedem Feature Modul einen Dokumentations-Ordner anlegen und eine jeweilige Dokumentationsartefakt anlegen, zum Beispiel mit der Namenskonvention „readme<Modulname>.adoc“ (alternativ in snake_case).
Ein beispielhaftes Layout für Feature-Module könnten sein:
- Modulname
- Warum gibt es das Modul
- <Modul>operationen (Geschäftslogik)
- Besonderheiten, Links zur Dokumentation von Fremdsystemen
- Abhängigkeitsgraphen auf Modulebene mit farblichen Unterscheidungen
- Von wem wird das Modul aufgerufen, welche Module ruft es auf
- Hellblau: Das zu beschreibende Modul
- Gelb: Designsystem
- Orange: Module, die als deprecated markiert wurden
- Eine Referenzierung auf eine Swagger-Schnittstelle (am besten über einen Link)
Documentation-as-a-code als Modulbeschreibung im Frontend
Analog könnte im Backend im Kontext einer Microservices Architektur ein mögliches Layout für die jeweiligen Microservices folgendermaßen aufgebaut werden:
- Microservices Name
- Warum brauchen wir den Microservice
- Referenz auf Microservice Referenzarchitektur (Schichten, Onion)
- Abhängigkeitsgraphen auf Microservice Ebene mit farblichen Unterscheidungen
- Von wem wird der Microservice aufgerufen, welche Microservices/Fremdsysteme ruft es auf
- Hellblau: Der zu beschreibende Microservice
- Orange: Microservices/Fremdsysteme, die als deprecated markiert wurden
- Gelb: Fremdsysteme
- regelmäßige Prozesse: z.B. nächtlicher Sync/Cronjob
Zusätzlich würde man im Projekt Root, sowohl im Frontend als auch Backend, ein Dokumentationsartefakt erstellen, welches die Modulstruktur beschreibt und Legenden für die wiederkehrenden Diagramm-Beschreibungen erläutert.
Weiterhin kann man die Dokumentationsabschnitte in statische und automatisierte Bereiche unterscheiden. Der Code für den Abhängigkeitsgraph der jeweiligen Module/Services kann so etwa durch ein Skript mithilfe von Codeanalyse automatisiert generiert werden.
Fazit zum Konzept Documentation-as-a-Code
Zusammenfassend lässt sich sagen, dass „Documentation-as-a-Code“ die Erstellung und Pflege von Dokumentationen optimiert, um Konsistenz, Genauigkeit und Zugänglichkeit sicher zu stellen.
Indem die Dokumentation als Code behandelt wird, können Teams effizient zusammenarbeiten, Workflows automatisieren und die Gesamtqualität von Softwareprojekten verbessern. Ein weiterer entscheidender Vorteil ist die Versionierung der Dokumentationen sowie die Verlinkung zu Dokumentationen von Fremdsystemen, die einen signifikanten Mehrwert für das Verständlichkeit und die Korrektheit beim Lesen der Dokumentation bringt.
Diese Paradigmenänderung führt zu einer gesteigerten Entwicklerproduktivität, reduzierten Fehlern und einem gestärkten Vertrauen der Benutzer:innen in die Dokumentation.
Es ist an der Zeit „Documentation-as-a-Code“ zu einem integralen Bestandteil Ihres Softwareentwicklungsprozesses zu machen. adesso mobile setzt erfolgreich Documentation-as-a-Code in verschiedenen Kundenprojekten ein, und unterstützt Sie gerne bei der individuellen Beratung für Ihr Projekt. Unsere Expert:innen stehen Ihnen bei Bedarf zur Verfügung – wir freuen uns auf Ihre Kontaktaufnahme!
