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.
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).
