Allein das Wort „Dokumentation“ führt bei vielen Entwicklern schon zu angestrengtem Stirnrunzeln. Wenn Dokumentation den Spaß an der Arbeit raubt, zur reinen Pflichterfüllung verkommt oder gar darauf verzichtet wird, ist es an der Zeit, sich mit einer besseren Herangehensweise auseinander zu setzen. Als Belohnung winken Zeitersparnis, höhere Qualität und weniger Frust.\r\n

Bevor wir einsteigen, möchte ich kurz den Rahmen für diesen zweiteiligen Artikel abgrenzen, denn Dokumentation kann im Umfeld der Softwareentwicklung in unterschiedlicher Weise geschehen. Viele Informationen, die im Zusammenhang mit Sourcecode stehen, dokumentieren wir am besten auch direkt dort in Gestalt von Kommentaren. Ich möchte mich in diesem Artikel jedoch bewusst auf die Informationen konzentrieren, für die Kommentare kein geeignetes Medium sind, wie es zum Beispiel auf Architektur- oder Prozessbeschreibungen zutrifft. Dazu gleich mehr – schauen wir uns zunächst an, woher eigentlich die Anstrengung in der Dokumentationsarbeit rührt.

Warum es uns so schwer fällt Dokumentation zu schreiben

Als Entwickler erfahren wir während unserer täglichen Arbeit tolle Erfolgserlebnisse. Wenn wir ein neues Feature umgesetzt haben, dürfen wir uns über den Fortschritt in unserem Produkt freuen. Auch wenn wir einen Bug beheben, wissen wir, dass wir ein Problem aus der Welt geschafft und unsere Anwendung ein bisschen besser gemacht haben. Und wenn wir Dokumentation schreiben? Passiert erst einmal nichts. Der Aufwand, den wir heute investieren, wird sich irgendwann in der Zukunft auszahlen – in manchen Fällen auch nie. Feedback zur Dokumentation ist sehr selten. Die Momente meiner Berufslaufbahn, in denen jemand zu mir kam und gesagt hat „Danke, deine Dokumentation hat mir viel Zeit erspart“, kann ich an einer Hand abzählen. Im besten Fall profitiert man irgendwann selbst von der eigenen Dokumentation und merkt dann: ohne sie, wäre das jetzt richtig anstrengend geworden.

Erschwerend kommt hinzu, dass wir nun einmal Entwickler sind, die Fähigkeiten wie technisches Verständnis und analytisches Denken zu ihren Kernkompetenzen zählen dürfen. Schreiben gehört in der Regel nicht dazu. Es ist Bürokratie, die wie in vielen anderen Berufen auch, als lästig empfunden wird. „Die Zeit kann man besser nutzen“ ist ein beliebtes Argument, das häufig nicht einmal ausgesprochen werden muss, weil die Liste an offenen Anforderungen ohnehin überquillt.  Mit diesen Umständen im Bewusstsein, ist es nicht mehr verwunderlich, dass Dokumentation in unserem Alltag – freundlich ausgedrückt – niedrige Priorität genießt. Aber es gibt tolle Möglichkeiten, um aus anstrengender Dokumentationsarbeit einen leichtgewichtigen Prozess zu gestalten, der uns hilft noch bessere Produkte zu implementieren. Bevor wir uns das genauer ansehen, werfen wir zunächst einen Blick darauf, worin die Chancen von Dokumentation bestehen.

Aus welchem Grund Dokumentation schreiben?

Dokumentation folgt keinem Selbstzweck. Nicht wegen der guten Sitte, sondern weil alles, das wir in unserem Beruf tun, schlussendlich zu einer Wertsteigerung innerhalb des Unternehmens führen muss, sollte Dokumentation geschrieben werden. Mit ihrer Hilfe, kann Wissen, das unter hohem Ressourceneinsatz im Unternehmen erarbeitet wurde, konserviert werden, damit es zukünftig mit deutlich weniger Aufwand erneut angewendet werden kann. Oder anders ausgedrückt: Wenn ich heute ein Problem löse, kann ich durch gute Dokumentation meinem Team bei erneuter Auseinandersetzung mit dem Problem viel Zeit und meinem Arbeitgeber damit Geld ersparen. Diese Ressourcen können dann an anderer Stelle für weitere wertsteigernde Zwecke wie beispielsweise neue Features eingesetzt werden. Der Aufwand, der für die Dokumentation investiert werden muss, wird sich langfristig in einer Effizienzsteigerung auszahlen, weil in zeitintensiven Arbeitsschritten auf bewährte Lösungsvorlagen zurückgegriffen werden kann.

Doch der Zweck von Dokumentation geht über Zeitersparnis hinaus, denn mit ihrer Hilfe kann auch Qualität sichergestellt werden. Häufig wiederholen sich in der Softwareentwicklung Probleme, die mit standardisierten und gut dokumentierten Lösungswegen in identischer Weise bei gleichbleibender Qualität gelöst werden können. So hilft eine User Interface Pattern Library, um Wildwuchs und Inkonsistenz in der Benutzeroberfläche einer Anwendung zu vermeiden. Ebenso kann eine Dokumentation über die Softwarearchitektur den Entwicklern bei entsprechender Größe einer Anwendung eine gute Anleitung bieten, um die richtigen Stellen sowie die richtige Art und Weise für die Umsetzung ihres Vorhabens im Code zu bestimmen. Fehlentscheidungen, die nachträglich aufwendig korrigiert werden müssten, werden vermieden.

Auch das Verfassen der Dokumentation selbst, kann als eine Optimierungsmaßnahme für ausgereifte Lösungen erachten werden. Während des Schreibens setzt man sich aus einer anderen Perspektive, nämlich der des zukünftigen Nutzers, mit der Lösung auseinander und gewinnt dadurch andere Einsichten. Diese Einsichten führen dazu, dass Lücken und Mängel aufgedeckt werden. So kann beispielsweise bei der Dokumentation eines Build-Prozesses auffallen, dass dieser noch unnötig kompliziert vonstattengeht und vor Auslieferung weiter verbessert werden sollte.

Und nicht zu vergessen ist, dass die Dokumentation auch einen wichtigen sozialen Aspekt im Team erfüllt. Wer sorgfältig dokumentiert, reduziert Frust und Ärger im Arbeitsalltag seiner Kollegen.  Außerdem bleibt allen mehr Zeit, für die Dinge, die beim Entwickeln wirklich Spaß machen. Wir stehen ja nicht morgens auf, um durch mühsames Erforschen herauszufinden, welche Rechte an den Benutzer vergeben werden müssen, damit eine Anwendung läuft. Und auch die Lösung für eine Fehlermeldung, die nicht unter den Top 3 bei Google steht, ist eine wertvolle Information, die weitergegeben werden sollte. Wenn alle im Team verantwortungsbewusst dokumentieren, entsteht ein Kreislauf, in dem jeder von den Erfahrungen der anderen profitieren kann und dadurch für alle schnellerer und besserer Fortschritt ermöglicht wird. Das wird nicht nur dem Unternehmen dienen, sondern auch unserer persönlichen beruflichen Entwicklung.

Was dokumentiert werden sollte und was nicht

Gut, sprechen wir endlich darüber, was es eigentlich zu dokumentieren gilt. Wir haben ja gerade gelernt, dass Qualität ein guter Grund für eine Dokumentation ist. In Fällen, in welchem durch Konsistenz und Standardisierung ein gewisser Qualitätsanspruch erfüllt werden soll, braucht es eine Dokumentation, die den notwendigen Rahmen dafür definiert. Das kann die bereits erwähnte Pattern Library für das User Interface Design sein, in der die einzelnen Komponenten katalogisiert und mit aussagekräftigen Erklärungen sowie praxisnahen Beispielen versehen werden. Ein ähnlicher Anwendungsfall, der sich aber auf die Welt hinter dem Grafischen fokussiert, ist ein Katalog für Sourcecode-Patterns, die wir seit Jahren pflegen und intern „Company Patterns“ nennen. In einer Anwendung, die eine gewisse Größe erreicht hat, wiederholen sich identische Probleme in unterschiedlichen Domänen. Man kann der Anwendung viel unnötige Komplexität bei gleichzeitig höherer Qualität ersparen, wenn diese Probleme immer wieder in identischer Weise gelöst werden. Ein entsprechendes Nachschlagewerk mit Erklärungen, aussagekräftigen Begründungen für die jeweiligen Lösungswege und adäquaten Code-Beispielen macht’s möglich.

Zeitersparnis ist ebenfalls ein Anspruch, den wir an Dokumentation haben dürfen. Und wofür benötigen wir besonders viel Zeit? Für die Dinge, die wir nicht alltäglich tun und zunächst den Weg zum Ziel suchen müssen. Wie schön kann der doch sein, wenn uns dann ein interner Guide über eine schnelle Abkürzung führt. Typische Inhalte für solche Guides sind komplexe Schnittstellen zu externen Systemen, aufwendige Prozesse in der Anwendung oder Arbeitsabläufe wie die Indexpflege in einer Datenbank, die nicht alltäglich durchgeführt werden. Mit einer Aufbereitung entsprechend der Zielgruppe können solche Dokumentationen ohne Umschweife präzise Wissen vermitteln und den Weg zum Ziel entsprechend abkürzen. Zielgruppengerecht meint, dass sich ein solcher Guide in der Regel an sattelfeste Entwickler richtet, die ihr Handwerk verstehen, und keine grundlegenden, sondern spezifische Fragen zu bestimmten Anwendungsfällen haben. Ein gutes Beispiel ist die Internationalisierung einer Anwendung also der Umgang, mit Datums-, Zeit- und Zahlenformaten sowie Textübersetzungen. Schon allein aufgrund verschiedener Produktausrichtungen, Unterschieden in der zugrundeliegenden Technologie sowie historisch gewachsenem Sourcecode, ist das ein Problem, das von Anwendung zu Anwendung in immer wieder unterschiedlicher Weise gelöst wird. Selbst Entwickler mit langjähriger Berufserfahrung, werden sich in diesem Zusammenhang immer wieder die gleichen Fragen stellen müssen. Das lässt sich abkürzen, wenn in einem Guide die Antwort auf die Frage „Wie kann ich im Vue-Frontend ein Datetime-Objekt entsprechend der Zeitzone des Benutzers formatieren?“ nachgeschlagen werden kann.

Doch nicht immer müssen es längere Texte sein. Auch die Dokumentation „im Kleinen“ darf nicht unterschätzt werden. Das gilt insbesondere für den Umgang mit Bugs, also in Situationen, in denen Schaden entstanden ist. Aus Fehlern muss man lernen und sich mit ihnen auseinandersetzen. Dafür sollten ihre Ursache, ihre Auswirkung und ihre Lösung festgehalten werden. Besonders letzteres wird wieder zu einer Zeitersparnis führen, sollte der Fehler erneut auftreten – wir wissen ja, dass wir nicht in einer idealen Welt leben. Ein anderer Fall für Mini-Dokumentation sind Entscheidungen. Wie oft werden Lösungsansätze während des Implementierungsprozesses noch einmal angepasst oder gar von Grund auf verändert? Es wäre wichtig und mit geringem Aufwand zu erledigen, die eigentlichen Gründe dafür in der User Story zu dokumentieren, damit diese zu einem späteren Zeitpunkt nachvollzogen und Diskussionsschleifen vermieden werden können.

Umstände, die eine Dokumentation erfordern, gibt es unendlich viele und sie alle zu benennen, ist unmöglich. Und sicherlich kann auch die Frage, ob überhaupt eine Dokumentation erforderlich ist, nicht pauschal beantwortet werden. Sind wir im Zweifel, besprechen wir das immer im Team.  Bei der Entscheidung helfen uns typische Indikatoren wie in der folgenden Liste dargestellt, die einen Hinweis darauf geben, dass eine Dokumentation sinnvoll sein könnte.

Und schließlich werfen wir einen Blick darauf, welche Inhalte nicht in eine selbstverfasste Dokumentation gehören, weil sie zu keiner Wertsteigerung führen, aber dennoch Kosten in der Entstehung verursachen. Das sind vor allem Informationen, die schon an anderer Stelle stehen und mit wenig Mühe von dort abgerufen werden können. Wenn die Lösung auch schnell mittels einer Google-Suchanfrage herauszufinden ist, kann entweder ganz auf Dokumentation verzichtet oder sie zumindest auf einen Link zum besten Blog- oder Forums-Beitrag reduziert werden. Ebenso verhält es sich mit Informationen zu eingesetzten Drittanbieter-Technologien wie Frameworks und Bibliotheken, die besser in der Original-Dokumentation des Herstellers nachgelesen werden sollten.

Die richtige Plattform für Dokumentation

Damit das Dokumentieren gelingen kann, sollten einige Rahmenbedingungen erfüllt sein, die ein positives Umfeld dafür schaffen. Das beginnt bei einer guten Erreichbarkeit der Dokumentation, damit in dem Moment, indem der wertvolle Gedanke auftritt, keine lästigen Hürden überwunden werden müssen. Generell gilt: Je „näher“ am Code desto besser. Sämtliche Barrieren zwischen Code und Dokumentation z.B. eine Benutzerauthentifizierung oder durch andere Benutzer gesperrte Word—Dokumente sollten tunlichst aus dem Weg geräumt werden. Entwickler dürfen beim Dokumentieren nicht das Gefühl haben, die Entwicklungsarbeit unterbrechen zu müssen, denn es ist Teil der Entwicklung. Nur wenn hier eine schnell überwindbare Brücke zwischen Code und Dokumentation existiert, wird das auch so wahrgenommen werden. Alles andere würde dazu führen, dass wertvolles Wissen, das meistens nur im Moment seiner Entstehung so präsent ist wie zu keinem späteren Zeitpunkt mehr, zumindest teilweise verloren geht und dem Unternehmen zukünftig nicht als wieder abrufbare Ressource zur Verfügung steht.

Die Wahl des Dokumentationsmediums ist also ein entscheidender Faktor. Wer jetzt aber glaubt, sich auf die Suche nach einer teuren Enterprise-Knowledge-Management-Plattform machen zu müssen, der liegt falsch. Wir haben die besten Erfahrungen mit einfachen Mitteln gemacht: Primitive HTML-Dateien, die in einem dedizierten Git-Repository, das als unser zentrales Nachschlagewerk fungiert, gesammelt werden. Dank Git genießen wir alle klassischen Vorteile des Source Controls und können die Dokumentation gut in den Review-Prozess integrieren. Mit HTML bewegen wir uns – zumindest als Webentwickler – in einem Milieu, das uns gut vertraut ist und gleichzeitig können wir diese Dokumentation in unserer üblichen, ebenso vertrauten, Entwicklungsumgebung bearbeiten. Darüber hinaus steht uns die volle Freiheit an Möglichkeiten von JavaScript und CSS zur Verfügung, um die Nutzung der Dokumentation so praktisch wie möglich zu machen.

Und das führt uns zur nächsten wichtigen Rahmenbedingung: Als Leser muss mir eine Dokumentation Spaß machen und in möglichst kurzer Zeit möglichst viele „Aha-Erlebnisse“ produzieren. Wichtige Voraussetzung dafür ist, dass ich mich darin schnell orientieren und navigieren kann. Um das zu fördern, haben wir ein kleines Set aus verschiedenen JavaScript-Tools zusammengetragen. Eines davon generiert vollautomatisch ein Inhaltsverzeichnis aus sämtlichen Überschriften des Dokuments. Ein anderes verlinkt alle Nummern im Text, die dem Schema „#12345“ entsprechen, zum jeweiligen Issue in unserer Product Management Plattform. Mit Mermaid bauen wir in kurzer Zeit schicke Diagramme zusammen und dank reveal.js können wir kleine Präsentationen gestalten, die für unsere Zwecke sogar Power Point übertreffen, weil Code-Highlighting schon dabei ist.  Es lohnt sich Zeit für solche Optimierungen zu investieren, denn sie sind ein großer Hebel, um die Akzeptanz und Nutzungsfrequenz der Dokumentation zu verbessern.

Doch das gelingt nicht nur durch Praktisches, sondern auch durch Schönes. So, wie viel in das visuelle Design einer Anwendung investiert wird, darf auch in die User Experience der Dokumentation investiert werden. Nichts macht beim Lesen weniger Freude, als ein Berg aus schlecht formatiertem, hässlichem Text. Dafür muss man auch gar nicht so viel selbst investieren, denn die Entwicklerteams von Frontend-Frameworks wie Bootstrap und Foundation haben großartige Vorarbeit hinsichtlich Typographie, Responsiveness und Struktur geleistet, von der die Dokumentation wunderbar profitieren kann. Ein solches Framework in Kombination mit etwas Anpassung für das Corporate Design des Unternehmens schafft einen schönen Rahmen, der das wertvolle, hart erarbeitete Wissen würdigt.

Fazit

Wir kennen jetzt die Ursachen für die Schwerfälligkeit beim Schreiben von Dokumentation. Wenn wir uns über diese hinwegsetzen, können wir mit hochwertiger Dokumentation die Qualität unserer Produkte verbessern sowie Zeit und dem ganzen Team Frustration ersparen. Neben einem Konsens über die eigentlichen Inhalte, ist eine geeignete Plattform die wichtigste Voraussetzung, damit Dokumentationsarbeit ihren tatsächlichen Mehrwert entfalten kann. Damit diese Arbeit dann auch in der Praxis umgesetzt werden kann, werden wir uns im zweiten Teil dieses Artikels drei konkrete praktische Regeln ansehen, mit deren Hilfe jeder bessere Dokumentation schreiben kann. Außerdem sehen wir uns an, wie sie in die Teamprozesse integriert und langfristig für eine aktuelle, lebendige Dokumentation gesorgt werden kann.