Tech 20. Oktober 2021 von Brian Widtmann 10 Leseminuten Qualität dank Dokumentation des Codes

Wenn es schnell gehen muss und die Features rasant implementiert werden, hapert es oft an der Dokumentation des Software-Codes. Entweder fehlt die Dokumentation komplett oder wird nicht ausreichend nachgeführt. 

Die Herausforderung Code-Dokumentation

Wieso soll man viel Zeit in das Nachführen der Dokumentation des Codes stecken? 

Oft ist das Wissen in den Köpfen der Projektmitarbeiter vorhanden und die Dokumentation wird vernachlässigt. Doch was ist zu tun, wenn ein neuer Mitarbeiter eingeschult wird und das Wissen nicht mehr abrufbar ist, weil die Software-Lösung bis anhin ohne Probleme lief? Dann muss der neue Mitarbeiter den ganzen Code mühsam durchgehen oder beansprucht die Zeit seiner Kollegen, um die Applikation zu verstehen. 

Eine Methode die Dokumentation aktuell zu halten und effizient zu schreiben, ist Docs-as-Code

Header-Code
Software-Code. Photo by Pankaj Patel on Unsplash

Weshalb oft ungenügend dokumentiert wird?

Word ist für die Dokumentation ungeeignet

Heutzutage werden im Voraus Word-Dokumente erstellt, in denen das Konzept für die zukünftige Lösung beschrieben werden soll. Oft wird das Dokument, welches vom Team abgenommen wurde, nicht mehr weiterentwickelt und Änderungen fliessen nicht in die Dokumentation ein. Auch schwirren diverse Versionen des Konzepts umher, weil es z.B. im E-Mail-Verkehr als Attachement zu oft versendet wird.

Des Entwicklers unliebster Job

Der Entwickler hat keine Lust nach jeder Code-Änderung oder nach jedem Abschluss eines Features, die Dokumentation in den Tiefen der File-Ablage zu suchen, Ergänzungen anzubringen und sich mit den Formatierungen von Word herumzuschlagen. Man schiebt den Task der Dokumentationsergänzung auf einen späteren Zeitpunkt. Das hat zur Folge, dass die Doku nicht oder ungenügend nachgeführt wird.

Verschiedene Datei-Formate für dieselbe Dokumentation

Auch ist es schwierig sich zu einigen, in welchem Format die Dokumentation erstellt werden soll. Intern benutzt man beispielsweise das Wiki Confluence, doch der Kunde verlangt eine PDF-Datei, Word oder sogar Excel.
 

Docs-as-Code: Die Lösung für saubere und aktuelle Dokumentation

Unser Ansatz einer stets aktuellen Code-Dokumentation heisst Docs-as-Code. Documentation as Code bezieht sich auf eine Philosophie, die besagt, dass man die Dokumentation mit denselben Werkzeugen wie den Code schreiben sollte. Die Dokumentation wird direkt im Code kreiert und generiert auf Wunsch z.B. ein PDF oder erstellt Wiki Seiten.

Dadurch, dass die Dokumentation mit Docs-as-Code versioniert wird (beispielsweise mit Git), kann automatisch die jeweils neuste Version der Dokumentation generiert werden.

Autoren in Docs-as-Code

Es kann genau nachverfolgt werden, welcher Entwickler welche Änderung in die Dokumentation geschrieben hat. Somit kann u.a. der Mitarbeiter bei Fragen auf diejenige Person zugehen und die Unklarheiten klären. 

Inline mit dem Source-Code

Mit der Methode von Docs-as-Code ist die Dokumentation neben dem eigentlichen Sourcecode abgelegt. Das hat den Vorteil, dass der Entwickler die Dokumentation gleich während dem Programmieren nachführen kann.  

Die richtigen Tools

Mit dem Tool-Set von docToolchain können zahlreiche Dokumentformate wie z.B. PDF aus einer Quelle erstellt werden. 

Die nachstehende Animation zeigt die Funktionsweise von Docs-as-Code auf:
 

Dokumentation für Schulungen

Neben all diesen Vorteilen kann die Dokumentation beim Kunden z.B. als Schulungsunterlager dienen. Die Tools können so konfiguriert werden, dass beim Erstellen der Dokumentation die zu technischen Details weggelassen werden und nur die Übersicht eines Systems erhalten bleibt (siehe nachstehende Grafik).

Beispiel PDF Docs-as-Code
Teilen