Dokumentation als KVP: vom Dokumenten Management System DMS bis zum Doku‑Showbiz fürs Audit

Da ich heute Code im wesentlichen zu Schulungszwecken schreibe und den Quellcode auch weitergebe, erlebt ich es regelmäßig: Wenn es schwer fällt, die Funktionsweise des Codes für Andere zu beschreiben, taugt er nichts. Er ist zu kompliziert. Ich entzerre, entferne besonders „coole“ Bestandteile, deren Entwicklung viel Spaß gemacht hat, auf die ich natürlich besonders stolz bin und bei denen es mir sehr schwer fällt, sie zu entfernen. Manchmal löse ich das Dilemma auf, indem ich mehrere Abschnitte mit dem gleichen Zweck schreibe und wahlweise ansteuere: So zeige ich einen lausigen Programmierstil, den qualitativ hochwertigsten im Sinne des gesamten Software Development Life Cycles nach den DevOps‑Prinzipien und eine coole Lösung, die ich selbst nach einem halben Jahr kaum noch verstehe. Aber klar: ich code speziell für die Weiterbildung, z.B. in meinen Kursen zu python + ML/KI. Nebenbei: python ist eine der wichtigsten Sprachen für DevOps‑Pipelines (z.B. das Bash‑Scripting). Den Grundsatz halte ich für verallgemeinerbar: eine zeitnahe Dokumentation der aktiven Codezeilen in semantisch bedeutsamen Kommentarzeilen und Beschreibungsdokumenten führt zu Reflexion und dann hoffentlich auch Verbesserung des Codes. Haben wir mit dem V‑Modell und DevOps den Blick auf den gesamten SDLC bis zur Außerbetriebsetzung in vielen Jahren erweitert, entsteht qualitativ höherwertiger aktiver Code. Ein gutes Gedankenmodell ist die Rubber‑Duck‑Strategie: man beschreibe den Code so, dass eine Quietscheente oder ein Neuling ihn zügig versteht. Es gibt nicht allzu viel zwingende Notwendigkeit für echtes „Bleeding‑Edge‑Coding“. Dazu ein zugegebenermaßen banal klingender Führungsgrundsatz:

Die Arbeitsweise, der Führungskräfte Anerkennung zollen, bestimmt die Art des Ergebnisses.

Sicherheitshalber eine nicht weniger banale Ergänzung: Wirksame Anerkennung ist eine, die beim Empfänger das Selbstwertmotiv positiv aktiviert. Diese Herausforderung an Führung ist längst nicht immer so simpel, wie der Satz anzudeuten scheint. Man beachte auch: das Selbstwertmotiv ist nur eines von acht wissenschaftlich gut belegten Motiven des Motivsystems. Ein einziger Fehler und wir haben den Mitarbeiter entgegen unserer Ziele motiviert. Es braucht rund sieben positive Aktivierungen danach, um die eine negative auszugleichen. Aber ich schweife ab.

Ein kurzer Gedanke zu KI im Coding und bei der Erstellung der Dokumentation. KI kann heute bereits viel für uns tun: im Coding und im gesamten DevOps SDLC. In Zukunft ist noch viel mehr zu erwarten. Ich persönlich erlebe es in meinen Schulungen beispielsweise oft so, dass die von Teilnehmenden hinzu gezogene KI mir neue Ideen zum Coding liefert, die manchmal eleganter sind als meine bisherigen Lösungen. KI erweitert meinen Horizont als Entwickler. Cool!
Aber: keine oberhalb des Placebo‑Effektes wirksame Medizin ist ohne Nebenwirkungen. Ein automatisiertes Erstellen des aktiven Codes samt Dokumentation kann schleichend vom Code entfremden (Dank an Karl Marx für die Formulierung 😉) und senkt damit die Coding‑Intelligenz im Unternehmen ab, erst unmerklich und dann immer schneller. Bereits während noch alle jubeln, steigt die Entropie des Codes bereits an, was in der Zukunft Probleme macht. Aber wie fasst der Nobelpreisträger Kahneman Erkenntnisse zusammen: „Der Mensch, der ich morgen sein werde, ist mir ein Fremder.“ Na ja, und in drei Jahren ist man eh' bei einem anderen Unternehmen. Nach mir die Sintflut. Lassen Sie sich rechtzeitig(!) eine Testmetrik einfallen: vielleicht geben Sie einer unschuldigen Person, einem Praktikanten oder dem IT studierenden Kind eines Mitarbeiters, Ihren aktiven Quellcode samt Dokumentation. Sie überlegen sich anhand der Liste der 80 Fragetechniken eine sog. Itembatterie und lassen die unschuldige Person diese bearbeiten. Schließlich entsteht durch Aggregation ein Kennwert (KPI) für den Entropiezustand des Codes in Ihrem Hause. Ab dem zweiten Mal können Sie auf die in Ihrem Hause bestehenden Tendenzen schließen. Und auf sehr viel mehr. So weit nur eine von vielen möglichen Ideen, basierend auf gängigen Methoden empirischer Forschung. Auch davon gibt es ein ganzes Arsenal an Tools zum Erkenntnisgewinn, logisch. Als Hochschuldozent bin ich gerade zu diesen Themen seit vielen Jahren dicht am Ball.

Und damit zu eher standardmäßigen Perspektiven auf Dokumentation 🙄:
Wir erinnern uns daran: Unter „Software“ verstehen wir alle digital speicherbaren Inhalte. Damit ist Dokumentation Teil der Software. Insbesondere semantisch bedeutsame Kommentarzeilen erweisen sich für die spätere Wartbarkeit und Wiederverwendung als unendlich wertvoll. Nicht nur bei Oldtimern und Legacy‑Systemen.

Im Style‑Guide könnte als einer von vielen Punkten bei Änderungen im aktiven Code stehen: „Beschreiben Sie (1), WAS Sie geändert haben. Beschreiben Sie (2), WARUM Sie es geändert haben. Beschreiben Sie (3), WARUM WELCHE anderen Lösungen sich als weniger tauglich erwiesen haben.“ Logo, oder? Das erspart den Nachkommen im Coding‑Job oder dem Betriebsteam viel Zeit, Frust und Ärger.

Der häufige Zustand von Dokumenten in realen Unternehmen ist, sagen wir mal, kreativ und heterogen‑divers. Schnell zur Lösung einer spontan‑lokalen Anforderung erzeugte Excel‑Strukturen und Schatten‑KI wechseln sich mit ewigen E‑Mail‑Eingängen auf diversen Endgeräten ab. Jeder kleine Schritt macht Erfolgsspaß und erzeugt (manchmal) eine Erleichterung. In Summe wandert diese Doku‑Drift dem Chaos entgegen: schlechter wird's ganz von selbst, dem zweiten Hauptsatz der Thermodynamik „Entropie“ entkommt man nicht ohne bewusste Anstrengung.

Aktuelle Lösung: ein KI‑Agentensystem, das sich durch das Chaos wühlt und immer genau die richtigen Dokumente findet und nutzt. Ein wunderbarer Freibrief für „weiter so“. Um einen gängigen Nerd‑Satz aus dem Coding zu bemühen: „Kann man so machen. Wird dann aber Kacke.“ Eine RCA (Root Cause Analysis) könnte allerdings zeigen, dass die Ursachen für eine ganze Reihe Probleme im Unternehmen tiefer verborgen liegen. Beheben wir eine einzige Wurzel‑Ursache, lösen wir typischerweise viele scheinbar ganz unterschiedliche Probleme, Brandherde und dichten so manche sprudelnde Kostenquelle, beginnend beim Recruiting. Fangen wir doch einfach mit dem Dokumenten‑Management an. Klarheit beim „Wo kommt was hin“ und „Wie genau hat es auszusehen“ und mehr fördert im Laufe der Zeit auch Klarheit in den Köpfen. Oder sollten wir es umgekehrt angehen? Die beste Antwort hängt ganz konkret von der Unternehmenskultur ab.

Eine erste, vorsichtige Botschaft an Führungskräfte lautet: Wer anerkennt, dass lauffähiger Code schnell erzeugt wurde, bekommt „Code now, fix later“ ohne wahrhaftig durchgeführtes Code Review. Wer hochwertige Dokumentation ausdrücklich anerkennt, bekommt tragfähige Strukturen für das Betriebsteam, die Wartung, Wiederauffindbarkeit und qualitativ hochwertige Dokumente. Auch bei Personalwechsel. Anerkennung, z.B. in Form von kompetentem, den Selbstwert des Empfängers steigernden Lob, ist nach Stand der Wissenschaft DER Treiber für Spaß und Leistung. Eingebaut in ein kluges, wirtschaftspsychologisch belegtes und tatsächlich auch gelebtes Gesamtkonzept der Personalführung kann aus der ungeliebten Dokumentationspflicht echte Freude werden. überlegen wir noch einen Schritt weiter: Coden macht Codern oft Spaß, Dokumentation nicht und das Beachten von Vorschriften (Compliance) schon dreimal nicht. Alleine aus diesen Gründ sollte Dokumentation als sehr viel lobenswerter angesehen werden, als dies meist der Fall ist. Anerkennung steuert Verhalten und Betriebsklima. Anerkennung erleichtert damit das Recruiting und mehr.

Lernen aus Fehlern mit Dokumentation: Blameless Post‑Mortems (BPM) aus DevOps Die Idee ist genau so einfach wie Klein‑Fritzchen es sich denken würde: Wem ein nicht‑vorwerfbarer Fehler unterläuft und wer diesen angemessen reflektiert, der hat an Weisheit gewonnen und sollte diese teilen. In einem BPM‑Dokument wird er folgendes freundlich und ohne peinliche Schuldzuweisung an Andere beschreiben:

• Was genau geschehen ist: die Vorfallsbeschreibung
• Präzision der Ursache für das Auftreten
• Vorgehen zum Abstellen des Fehlers
• Überlegungen dazu, warum der Fehler nicht früher aufgefallen ist
• Handlungsempfehlungen für die Zukunft
• [...]

Eine gute Führungskraft wird dafür sorgen, dass solche Dokumente aktiv gelebt werden und ‑eine von vielen Möglichkeiten‑ vielleicht eine Checkliste aus allen Berichten anfertigen. Klar, der Eingang eines solchen Berichtes findet ausdrückliche Anerkennung z.B. im (hoffentlich stattfindenden) Montagsmeeting. Wenn Sie jetzt in Ihren Kopf den Kommentar „Das kann man bei uns nicht machen“ auftauchen hören, haben Sie soeben ein Führungsproblem diagnostiziert. Machen Sie etwas aus Ihrer Erkenntnis! Nur für Sie persönlich, für die Abteilung oder für das gesamte Unternehmen. Stellen Sie sich jetzt bitte vor, ich würde hier 1.300 weitere Seiten schreiben ‑ so viel gibt es zum Forschungsstand der Führung als Ergebnisse vieler Experimente umzusetzen.

Als Wirtschaftspsychologe M.Sc. habe ich mir genau diese Themenfelder anhand tausendfacher (echt! Wenn auch anders, als Sie vielleicht denken 😉) Praxis angeeignet, eine ideale Ergänzung zum in der Industrie führungs‑ und softwareerfahrenen Ingenieur.

Reden wir jetzt darüber!