Karten, Gold und Gewürze: Warum vernachlässigte Dokumentation Ihr Projekt zum Scheitern bringen kann

Was war das Wertvollste, was die Entdecker früherer Zeiten von ihren Reisen mit nach Hause brachten? Gold und Gewürze? Falsch. Karten.

Christoph Kolumbus hätte seine berühmte Reise im Jahr 1492 nie unternommen ohne Karte von seinen Vorgängern entworfen. Ein Spionagespiel, um portugiesische Karten zu erhalten, legte den Grundstein für die Niederländische Ostindien-Kompanie, wohl das teuerste Unternehmen der Menschheitsgeschichte. Auf seinem Höhepunkt im Jahr 1637 war es 78 Millionen niederländische Gulden wert, ein Gegenwert von 7,9 Billionen US-Dollar in Dollar von 2017. Das sind mehr als 10 Billionen Dollar in Geld von 2024, mehr als Microsoft , Nvidia und Apple kombiniert Greifbare Schätze aus neuen Ländern waren kurzfristig wichtig, doch auf lange Sicht war es das Wissen, das den wahren Reichtum schuf.

Wie kommt es, dass wir das in der heutigen Welt der Technik oft vergessen? Wir streben nach sofortigem Erfolg und zögern oft, wertvolle Zeit und Ressourcen in die Erstellung und Pflege technischer Dokumentationen zu investieren. Um es mit den Worten des 17. Jahrhunderts auszudrücken: Wir stürzen uns auf Gold und Gewürze, ohne unsere Karten zu zeichnen, die uns wiederum zu viel mehr Gold und Gewürzen hätten führen können. Sind Sie skeptisch? Ahoi, schauen wir uns das genauer an …

Verrückter Code

„Wie Sie sich zweifellos erinnern, kann die hypnoide Stasis der neuronalen Muster des Gehirns von einem extra-elektromagnetischen Strahl gescannt werden, der –“ „Kommen Sie davon!“, sagte Ard Vark ungeduldig. „Was meinen Sie – wie wir uns zweifellos erinnern?“ Wie können wir uns daran erinnern, wenn wir es nie wussten? – Dieses Zitat aus Wacky World, einer Geschichte des großen Science-Fiction-Autors Edmond Hamilton, bezieht sich auf Marsmenschen, nicht auf Programmierer. Viele Leute betrachten Entwickler jedoch, als kämen sie von einem anderen Planeten – insbesondere diejenigen, die nur eine vage Vorstellung von Softwareentwicklung und ihrer Komplexität haben. Tatsächlich gehen Entwickler oft davon aus, dass andere Code genauso gut kennen wie sie, und halten technische Dokumentation häufig für unnötig. Diese Denkweise birgt das Risiko, dass das Projekt für Außenstehende genauso komplex und unverständlich wird wie eine „hypnoide Stasis“, was letztendlich den potenziellen Erfolg des Projekts gefährdet.

Die Zurückhaltung bei der Erstellung von Dokumentationen hat oft dieselben Gründe wie in anderen Bereichen: Sie erfordern einen erheblichen Zeit- und Finanzaufwand. Mit anderen Worten: Oft liegt es an purer Faulheit und dem Wunsch, Geld zu sparen – Hindernisse, die nicht leicht zu überwinden sind. Dokumentationen sind jedoch nicht nur redundante Informationen, die angeblich jedem klar sind; sie enthalten wichtige Details, die unverzichtbar sein können. Oft erschwert das Fehlen von Dokumentationen die Erkennung und Korrektur von Fehlern erheblich, erschwert Wartung und Aktualisierungen und erhöht den Zeitaufwand für die Einarbeitung neuer Teammitglieder. Während Teams ohne Dokumentation mit sich wiederholenden Aufgaben stecken bleiben, weisen Projekte mit gut strukturierter Dokumentation eine hohe Effizienz und Zuverlässigkeit auf – das ist eine Tatsache, keine bloße Meinung.

Ja, einige Programmierer behaupten, dass der von ihnen geschriebene Code so klar und verständlich ist, dass Dokumentation schlicht unnötig ist. In Wirklichkeit kann jedoch selbst der perfekteste Code für andere verwirrend sein oder mit der Zeit seine Klarheit verlieren. Was heute klar erscheint, kann morgen zu einem Rätsel werden. Könnten Sie beispielsweise problemlos mit einer einfachen Lochkarte aus den 70er Jahren umgehen?

Busfaktor, Burnout und andere fantastische Bestien

Theorie ist gut, aber die Praxis ist überzeugender. Hier sind einige Beispiele, die auf wahren Begebenheiten beruhen und bei denen nur die Namen der Personen und Unternehmen fiktiv sind. Diese kurzen Fallstudien behandeln die typischsten Probleme, die aufgrund schlechter technischer Dokumentationspraktiken entstehen.

Geschichte Nr. 1: Unfähigkeit zur Skalierung

Das Projekt „NoDocumentationPlease“, ursprünglich ein erfolgreiches Videostreaming-Startup, hatte aufgrund mangelhafter technischer Dokumentation ernsthafte Probleme bei der Skalierung. Als das Team erweitert werden musste, konnten neue Mitarbeiter ihre Aufgaben nicht vollständig verstehen und niemand konnte ihnen eine angemessene Erklärung geben. Ohne angemessene Unterstützung und Schulung verließen neue Mitarbeiter das Unternehmen schnell wieder. Dies verlangsamte nicht nur den Projektfortschritt, sondern führte auch zum Verlust wichtiger Talente und gefährdete letztlich die Gesamteffektivität und Zukunft des Projekts. Infolgedessen verließen die Streamer den Chat und das Projekt wurde eingestellt.

Geschichte Nr. 2: Wartungsprobleme

Das Unternehmen „IKnowEverything“ entwickelte eine Cloud-Plattform zur Datensynchronisierung und -speicherung. Anfangs schritt das Projekt schnell voran, doch mit der Zeit hatten die Entwickler Schwierigkeiten, die Plattform zu warten und zu aktualisieren, da es an klarer und aktueller technischer Dokumentation mangelte. Dies führte zu einer langsameren Entwicklung, mehr Fehlern und unzufriedenen Kunden. Schließlich begann das Unternehmen, seine alten Kunden zu verlieren, und neue Kunden wählten Konkurrenten mit stabileren und zuverlässigeren Lösungen. Die Umsätze gingen erheblich zurück, während die Kosten für ineffektive Wartung stiegen. Eine ordnungsgemäße Dokumentation der technischen Aspekte von Anfang an hätte ihnen eine erfolgreiche Skalierung ermöglichen können. Dies geschah jedoch nicht rechtzeitig. Folglich konnte das Unternehmen technische und finanzielle Herausforderungen nicht bewältigen und wurde geschlossen.

Geschichte Nr. 3: Burnout bei Entwicklern

Das Projekt „SmartestEver“ hatte mit ernsthaften Problemen zu kämpfen, weil sein Hauptentwickler Andrew, der sich um so ziemlich alles kümmerte, zurücktrat, nachdem er von den zahlreichen Fragen des Teams überwältigt worden war. Hätte „SmartestEver“ eine ordentliche Dokumentation gehabt, hätten Juniorentwickler einfach auf die FAQ zurückgreifen und Routineprobleme lösen können. Stattdessen bombardierten sie Andrew mit Fragen, und ohne ihn und die notwendige Dokumentation kam das Team einfach nicht weiter und das Projekt wurde eingestellt (drücken Sie F für Andrew).

Geschichte Nr. 4: Der Bus-Faktor

In der Firma „NoDocsNeeded“ wurde ein vielversprechendes Softwareprodukt von John, einem Schlüsselentwickler, entwickelt, der zwar über das gesamte Wissen verfügte, es aber nicht dokumentierte. Auch seine Manager machten sich nicht die Mühe, ihn zu überzeugen. Eines Tages ging John auf Geschäftsreise und kam einfach nicht zurück. Ohne Dokumentation oder Verständnis der Architektur und Logik des Produkts konnten die übrigen Teammitglieder im Grunde nichts tun. Das Projekt wurde eingefroren und das investierte Geld war verschwendet. Die Lektion ist einfach: Dokumentation und Wissensverteilung innerhalb eines Teams sind entscheidend, um die Abhängigkeit von einer einzelnen Person zu vermeiden. Übrigens suchen sie immer noch nach John …

Geschichte Nr. 5: Propheten sind bei Open Source nicht willkommen

Maria erstellte ihre erste Open-Source-Bibliothek, schrieb jedoch keine Dokumentation dafür. Niemand verstand, was die Bibliothek tat, und Maria beschloss, keine weiteren Bibliotheken mehr zu schreiben, da es ihr sinnlos erschien. Marias Projekt endete, bevor es überhaupt begonnen hatte, und sie beschloss, ihren Beruf zu wechseln.

Vom Schiffsjungen zum Kapitän

Ok, wir haben etwas Theorie und Praxis gelernt, jetzt tauchen wir in Forschung und Statistik ein. Stack Overflow-Entwicklerumfrage 2024 Staaten dass 84 % der Befragten technische Dokumentationen verwenden, um die Funktionsweise von Technologien zu verstehen. Doch selbst mit Dokumentationen können sie oft nicht die Antworten finden, die sie benötigen, wie die nächstbeliebtesten Ressourcen zeigen: Stack Overflow (80 %), schriftliche Tutorials (68 %), Blogs (61 %) und How-to-Videos (54 %). Microsoft Research: Der Alltag von Softwareentwicklern gefunden dass Entwickler im Durchschnitt 1-2 % ihres Tages (8-10 Minuten) mit Dokumentation verbringen, und 10,3 % der Entwickler sagen, dass sie aufgrund veralteter Dokumentation zu viel Zeit damit verbringen müssen, selbst nach Antworten zu suchen. Die Notwendigkeit von Dokumentation ist auch für die akademische Gemeinschaft ein großes Anliegen. Eine einfache Google Scholar-Suche nach <"documentation" AND "software"> Erträge über 4 Millionen Ergebnisse, was deutlich darauf hinweist, dass es eine große Anzahl wissenschaftlicher Veröffentlichungen zu diesem Thema gibt.

Die wichtigsten Schlussfolgerungen sind erstaunlich einfach: #1 – Jeder braucht Dokumentation, wenn es darum geht, Technik und/oder die Arbeit anderer Leute zu verstehen; aber #2 – Nur wenige Leute machen sich die Mühe, sie zu schreiben und zu pflegen; und folglich #3 – Viele Dokumentationen sind schlecht geschrieben, veraltet und im Allgemeinen nutzlos. Was also ist zu tun? Ändern Sie Ihre Motivation auf allen Ebenen.

Eine Gruppe von Forschern der HAN University of Applied Sciences und der Universität Groningen (beide in den Niederlanden) identifiziert Die häufigsten Probleme mit der technischen Dokumentation:

• Informelle Dokumentation, die oft von Entwicklern verwendet wird, ist schwer zu verstehen;

• Dokumentation gilt als Abfall, wenn sie nicht unmittelbar zum Endprodukt beiträgt;

• Die Produktivität eines Entwicklers wird nur anhand der Menge der funktionierenden Software gemessen.

• Die Dokumentation stimmt oft nicht mit der eigentlichen Software überein.

• Insbesondere in Umgebungen zur kontinuierlichen Softwareentwicklung konzentrieren sich Entwickler häufig nur auf die kurzfristige Entwicklung.

  
  

Kommt Ihnen das bekannt vor? Ich bin sicher, dass die meisten von uns in ihrer täglichen Routinearbeit auf die meisten oder sogar alle davon gleichzeitig gestoßen sind. Und es steckt mehr dahinter als nur Aufschieberei oder Ressourcenmangel. Einige dieser Probleme sind auf einen Mangel an angemessenem Management, langfristiger Planung und letztlich an strategischer Vision zurückzuführen. Und hier kommt der schwierige Teil, denn es liegt nicht nur an uns Entwicklern, diese zu lösen. Einige Probleme sollten von Managern, Produktbeteiligten oder sogar Firmeninhabern behandelt werden. Deshalb ist es entscheidend, dass angemessene Ansichten zu technischen Aspekten nicht nur ein nettes Beiwerk sind, sondern Teil der Grundwerte des gesamten Unternehmens, die von allen geteilt werden, vom Gründer bis zum Juniorentwickler.