Technisches Schulden Szenario #5: Der Code dokumentiert das System.
Leider haben einige langjährige Entwickler das Produktteam verlassen. Zusätzlich gibt es praktisch keine technische Dokumentation zum System. Auch die Architekturentscheide sind nicht mehr nachvollziehbar. Wie würdest Du vorgehen eine solche Art von technischen Schulden zu adressieren?
Das fünfte Szenario wie technische Schulden aufgebaut werden, dreht sich um technische Dokumentationen von Software-Systemen. Öfters geistert in Engineering-Teams der Spruch "Der Code dokumentiert das System." herum. Dieser Post beschreibt, warum diese Aussage ein Symptom von technischen Schulden ist und wie man diese Art von technischen Schulden adressieren kann.
Dies ist der fünfte Artikel, der sich damit befasst wie technische Schulden aufgebaut und adressiert werden können. Wenn Du die vorherigen Artikel lesen möchtest, klicke auf die nachfolgenden Links. 👇
Patrick Roos
Patrick Roos
Patrick Roos
Patrick Roos
Inhalt
Szenario
Ein neuer Entwickler startet heute. Als Einführung macht jedes Team-Mitglied eine technische Einführung in einen bestimmten Teil von ihrem Softwareprodukt.
Entwickler 1: Ich zeige Dir unsere Frontend-Architektur. Lass uns starten...
Entwickler 1 öffnet seine IDE.
Entwickler 1: Wie Du siehst, basiert unser Frontend hauptsächlich auf Angular.
Der neue Entwickler: Ah, okay. Cool. Wieso habt Ihr Euch für Angular entschieden?
Entwickler 1: Hm. Entwickler, welche nicht mehr für uns arbeiten, haben dies vor ca. zwei Jahren entschieden. Ich weiss die konkreten Gründe nicht mehr, warum man sich für Angular entschieden.
Entwickler 1: Browst durch den Code.
Entwickler 1: Hier siehst Du die Struktur von unseren Angular Modulen. Wie Du vermutlich erkennst, haben wir versucht den Code entlang der Business Domänen zu strukturieren. So hat jeder fachliche Teil sein eigenes Angular Module, welche jeweils via lazy geladen werden können.
Der neue Entwickler: OK - Was gibt es für Business Domänen im Software Produkt?
Entwickler 1: Ich arbeite primär in der Payment Domäne. Aber soweit ich weiss gibt es noch die Bestell-, Lieferungs und Weitempfehlungsdomäne. Ich weiss aber nicht viel über diese Domänen - ich kann sie lediglich aus der Code Struktur herleiten.
Der neue Entwickler: OK - kann ich irgendwo mehr über die Software Architektur nachlesen?
Entwickler 1: Ja - warte, ich zeige Dir die Dokumention in Confluence. Wir hatten vor einem Jahr die Aufgabe alles nachzudokumentieren.
Entwickler 1 öffnet die Dokumentation.
Entwickler 1: Du siehst die Dokumentation hier. Aber hm - ich denke die Dokumentation ist schon wieder veraltet. Am besten schaust Du Dir den Code an. Dieser dokumentiert eigentlich das System. 😀
Was ist das Problem?
Ein oftmals unterschätztes Problem in der Software Entwicklung ist die technische Schuld in der Dokumentation - oder auch bekannt als "Dokumentationsschuld".
Dabei gibt es drei Arten von Dokumentationsschulden:
👉 Fehlende Dokumentation
Es kann vorkommen, dass in Engineering Teams das folgende Prinzip herrscht: "Wir brauchen keine Dokumentation. Der Code dokumentiert das System."
Kann der Code wirklich ein System abschliessend dokumentieren? Ich bezweifle es.
Idealerweise, kann man einiges über die Businessdomäne oder angebundene Fremdsysteme aus dem Code herauslesen. Was man aber aus dem Code oftmals nicht herauslesen kann ist, welche Architektur-Entscheidungen getroffen wurden und vor allem wieso diese getroffen wurden.
Antworten zu den folgenden Beispielfragen können oftmals nicht aus dem Code hergeleitet werden:
- Warum wurde Angular als Frontend-Framework eingesetzt?
- Wieso ist die Backend-Komponente über Schichten strukturiert?
- Wie ist die Verteilungssicht des Software Systems?
- ...
👉 Veraltete Dokumentation
Die meisten Confluence-, Word oder PDF Dokumente, welche das System dokumentieren, sind bereits nach einigen Monaten wieder veraltet. Das System und dessen Dokumentation läuft auseinander.
So wird die bestehende (resp. veraltete) Dokumentation wertlos - vielleicht sogar hinderlich, da sie einen Entwickler auf den falschen Pfad führen kann da sie nicht mehr zum aktuellen System passt.
👉 Zu viel Dokumentation, die relevanten Teile fehlen aber
Die Kunst der Dokumentation ist es so wenig wie möglich - aber dennoch genau so viel zu dokumentieren, damit der Leser der Dokumentationdie relevanten Teile des Systems verstehen kann.
Es kann vorkommen, dass viel Dokumentation geschrieben wird, um ggf. organistorische oder prozessuale Rahmenbedingungen (oder aus sonstigen schwierig nachvollziehbaren Gründen) zu adressieren.
Solche Art von Dokumentation trifft meistens die Ziele nicht, den darin fehlen oftmals die relevanten Teile wie z.B. Architektur-Entscheidungen, Qualitätsszenarien mit den darunterliegenden nicht funktionalen Anforderungen.
Wie kann dieses Problem adressiert werden?
Strukturierte Architekturdokumentation erstellen dank arc42
Eine gute Vorlage für den Aufbau einer Architekturdokumentation ist arc42.
Die arc42 gibt die folgenden Teile der Dokumentation eines Software-Systems vor:
- Anforderungen und Ziele
- Rahmenbedingungen
- Scope & Kontext
- Lösungsstrategie
- Bausteinsicht
- Laufzeitsicht
- Verteilungssicht
- Querschnittsthemen
- Architekturentscheidungen
- Qualitätsszenarien
- Risiken und technische Schulden
- Glossar
Jedes dieser Kapitel kann als "Schublade" gedacht werden, in welcher man das passende Teil der Dokumentation versorgen kann.
Falls man noch gar keine Dokumentation hat, sollte man nicht mit einem grossen Dokumentationstask im Backlog starten à la "Dokumentier das Softwaresystem mal nach". Dies ist eher ein Anti-Pattern.
Aus meiner Sicht ist es effektiver die Dokumentation, während der Entwicklung von einem neuen Feature oder während eines Refactorings Schritt für Schritt die Dokumentation aufzubauen resp. zu ergänzen. Dadurch wird die Dokumentation kontinuierlich aufgebaut, aktualisiert und bleibt somit aktuell.
Tipp: Gernot Starke gab einen guten Talk über sparsame Dokumentation.
Erneuerung der veraltete Dokumentation mit "Documentation as Code"
Ein Ansatz um das das Problem von veralteter Dokumentation zu adressieren, ist es Dokumentation wie Code zu behandeln - auch bekann als "documnetation as code".
Das bedeutet, man schreibt resp. entwickelt 😀 die Dokumentation mit den gleichen Tools und der gleichen Methodik wie Code:
- IDE
- Source Code Management / Git-Flow
- Plain text markup (like Markdown, Asciidoc)
- Code (Documentation 😉) reviews
- Build system für das Bauen und Verteilen der Dokumentation
- Testen der Dokumentation, und messen von Metriken wie z.B. Lesbarkeit
Documentation as code erhöht die Wartbarkeit der Dokumentation, weil man von den Workflows und Qualitätsprüfungsmechanismen aus dem Software Engineering wie z.B. den Gitflow mit Pull Requests profitieren kann. So können Features geblockt werden, wenn die Dokumentation nicht entsprechend nachgezogen wurde. Zusätzlich werden Entwickler motiviert, direkt bei der Features-Entwicklung die Dokumentation mit ihren bekannten Tools zu erstellen.
Die folgenden Tools unterstützen bei der Umsetzung von documentation as code:
docToolchainModernisierung der bestehenden Dokumentation
Wie beim Refactoring von Code, kann man dies mit der technischen Dokumentation tun. Wenn man veraltete oder teilweise nicht mehr relevante Teile in der Dokumentation hat, kann man diese entlang der arc42 Vorlage überarbeiten.
Mögliches Vorgehen um das Refactoring einer veralteten Dokumentation zu planen:
- Initiierung der Architektur Dokumentation basierend auf der arc42 Vorlage, idealerweise nach dem oben verlinkten documentation as code Technologiestack im git repository der entsprechenden Software-Komponenten.
- Aufsetzen einer CI-/CD-Pipeline welche die Dokumentation baut und entsprechend verteilt.
- Identifikation der Teile der aktuellen Dokumentation welche in die arc42 Vorlage passen.
- Bei der Entwicklung von neuen Features, kann man kontinuierlich die relevanten Teile der alten Dokumentation ins neue Format migrieren.
Anschliessend hat man eine passende documentation-as-code Basis um eine stets aktuelle und nachvollziehbare Architektur-Dokumentation zu führen.
Fazit
Wenn man die Dokumentation wie Code behandelt "documentation as code", dann adressiert man folgende Probleme:
- Veraltete oder irrelevante Dokumentation, weil jeder Pull-Request von einem neuen Feature soll die aktualisierte Dokumentation beinhalten.
- Medienbruch- und Dokumentationsmüdigkeit, weil der Entwickler die Dokumentation direkt mit den Tools und der Methodik zu schreiben kann, wie er Code schreibt.
arc42 bietet eine solide Vorlage an, um eine neue Architekturdokumentation aufzubauen oder die existierende Dokumentation zu überarbeiten.
documentation as code kombiniert mit der arc42 Vorlage ist ein passender Dokumentationsansatz, um das Entwicklungsteam zu motivieren, eine wartbare und stets nachvollziehbare technische Architekturdokumentation zu schreiben.
Starte jetzt und ermögliche eine nachhaltige Dokumentation von deinem Software-System mit einem modernen Dokumentationsansatz.
Comments ()