Manchmal wird es zum Projektende noch einmal richtig zäh. Dann muss eine Dokumentation geschrieben werden, die vielleicht nie jemand liest und wenn doch vielleicht nicht versteht. Das geht auch anders. Mit drei einfachen Regeln und einer passenden Teamkultur lässt sich die Dokumentation ohne Anstrengung in die Entwicklungsarbeit integrieren.

Im ersten Teil dieses Artikels haben wir uns bereits angesehen, in wie fern Dokumentation nicht nur unseren Arbeitsalltag erleichtern, sondern auch den Erfolg dank Qualitätsverbesserung und Geschwindigkeitsgewinn maßgeblich steigern kann. Ebenso haben wir betrachtet, welche Rahmenbedingungen in Hinblick auf die Dokumentationsplattform erfüllt sein müssen. Daran wird dieser Teil anknüpfen, indem wir einen Blick drauf werfen mit welchen praktischen Regeln die Dokumentation schon während der Entwicklung locker von der Hand geht und wie wir als Team gemeinsam an sowie mit der Dokumentation arbeiten.

Praktische Regeln für eine gelungene Dokumentation

„Endlich! Es funktioniert!“ Damit die rätselhafte Fehlermeldung verschwindet, musste eine Kompatibilitätseinstellung im Datenbank-Server geändert werden. Wer kennt sie nicht, die Situationen, in denen nach Stunden anstrengenden Herumprobierens endlich eine Lösung gefunden wurde? Jetzt schnell abschließen und wieder dem nächsten Feature zuwenden – und die Falle schnappt zu. Gerade eben wurde wertvolles, teures Wissen generiert. Und dieses Wissen konzentriert sich momentan auf eine Person und ist dadurch sehr flüchtig, denn kein Mensch kann alle Fälle dieser Art auf Dauer im Kopf behalten. Ja gut, dann wird das eben dokumentiert. Aber später, jetzt erstmal weiter programmieren – auch falsch. Dokumentation wird gerne nach hinten geschoben und andere Aufgaben vorgezogen – warum das so ist, haben wir ja schon gelernt. Doch später, ist manchmal nie und später heißt auch, dass schon wieder ein Teil der besonders wichtigen Informationen aus dem Kopf verschwunden sein kann. Daher gilt:

Regel 1: Sofort dokumentieren Jetzt muss man natürlich zugeben, dass sofortige Dokumentation tatsächlich auch den Arbeitsfluss stören kann. Nicht immer ist der dokumentationsbedürftige Gegenstand wie im obigen Beispiel die Lösung, sondern lediglich ein Teil in einem ganzen Informationskomplex. Das heißt, die Entwicklungsarbeit muss unterbrochen, die Gedanken für die Dokumentation sortiert und die Schreibarbeit umgesetzt werden. Danach ist man gedanklich schon wieder ein ganzes Stück weit vom eigentlichen Problem entfernt. Das ist nicht nur anstrengend, sondern auch schlecht für die Produktivität. Wie lässt sich dem Dilemma entgehen? Ein Kompromiss ist die Lösung: Dokumentiert wird sofort, aber nur in kurzen, ungefilterten Stichpunkten. Das kann der Name eines Konfigurationsparameters sein, der unbedingt gesetzt werden muss oder der Name einer CSS-Klasse, der notwendig ist, um die neue Komponente Use-Case gerecht einsetzen zu können. Die Form spielt hier keine Rolle, es ist zu diesem Zeitpunkt nur wichtig, dass das wertvolle Wissen, das nur im Moment seiner Entstehung derart präsent ist, festgehalten wird. Der Stichpunkt dient einzig und allein als Gedankenstütze. Die eigentliche Ausformulierung und Gestaltung erfolgt zu einem späteren Zeitpunkt, wenn der Arbeitsfluss nicht mehr gebremst werden kann.

Und wenn der Zeitpunkt dann gekommen ist, kann man den Gedanken freien Lauf lassen, in Ruhe darauf los schreiben und reinhauen bis die Tasten richtig glühen. Vorsicht, hier lauert eine Gefahr, die teuer werden kann. Auch wenn es erfahrungsgemäß weniger Dokumentationswütige als Dokumentationsmuffel gibt, ist es wichtig sich bewusst zu machen, dass es auch ein zu viel an Dokumentation geben kann. Denn genauso wie jede Zeile Code eine Rechtfertigung verlangt, um die Komplexität nicht unnötig in die Höhe zu treiben, gilt das auch für jeden Satz in einer Dokumentation. Schließlich muss nicht nur Zeit vom Verfasser der Dokumentation investiert werden, sondern auch vom eigentlichen Publikum, das meistens nach einer konkreten Information sucht und diese auf dem kürzesten Wege erhalten möchte. Was nützt es der Kollegin, die eigentlich nur nach dem Namen für einen bestimmten URL-Parameter sucht, sich zunächst durch allgemeine Informationen über den Aufbau von Uniform Resource Locators (URI) zu wühlen, die mit Original-Auszügen des zugehörigen RFCs garniert wurden? Dokumentation sollte die wirklich wichtigen Informationen mit möglichst wenig Worten auf den Punkt bringen. Es gibt einen Trick, der unserem Gehirn dabei hilft, unnötiges wegzulassen und nicht in ausschweifende Prosa zu verfallen: das Schreiben in Aufzählungspunkten. Daraus können wir eine weitere Regel ableiten:

Regel 2: Fasse dich kurz und schreibe in Aufzählungspunkten
Der Stil von Aufzählungspunkten ist naturgemäß reduziert auf das Wesentliche. Dadurch wird die Gefahr in unnötige Ausschweifungen zu verfallen stark minimiert. Das wiederum erleichtert das Lesen und gibt dem Adressaten die Möglichkeit schnell die wesentlichen Informationen dem Text zu entnehmen. Viele der Informationen, die wir als Entwickler verarbeiten, sind ohnehin prädestiniert dafür, in Aufzählungspunkten wiedergegeben zu werden. Prozessabläufe oder Namenskonventionen in lange Fließtexte zu verpacken, dürfte durchaus auch für den Verfasser anstrengend werden.

Kehren wir zum Beispiel der Internationalisierung zurück und schauen uns an, wie die Dokumentation dazu im Kontext einer ASP.NET Anwendung aussehen könnte:

• Die Sprache für Übersetzungen wird zentral im Property Thread.CurrentThread.CurrentUICulture im Lifecycle-Event Application_AcquireRequestState der Global.asax-Datei festgelegt
• Die Ableitung der aktuellen Sprache erfolgt dort aus dem Property Language
• Die Browsersprache wird konsequent ignoriert, weil wir unseren Benutzern versprochen haben, dass sie immer ihre bekannte Benutzeroberfläche vorfinden werden, unabhängig vom Endgerät, mit dem sie sich anmelden.
• In den darüber liegenden Schichten kann auf die aktuelle Sprache je nach Technologie mittels folgender Properties zugegriffen werden:
  • Vue: locale
  • jQuery: Get(„Language“)
  • …

Auch wenn es sich hier um ein gekürztes Beispiel handelt, zeigt sich, dass es dank der Aufzählungspunkte möglich ist, verhältnismäßig viele Informationen in einer kleinen Menge an Text unterzubringen. Auf erläuternde Informationen z.B. zur Global.asax Datei wurde verzichtet, da sie einem ASP.NET Webentwickler in der Regel bekannt ist. Stattdessen liegt der Fokus auf Informationen, die auch gestandenen Entwicklern nicht bekannt sein können, weil sie Anwendungsspezifisch sind und folglich entweder mühsam im Code erforscht oder effizient in einer Dokumentation nachgelesen werden müssen.

Nicht selten wird ein langer Text im Sinne von „viel hilft viel“ als ein Qualitätsmerkmal von Dokumentationen missverstanden. Warum das nicht so ist, haben wir uns ja bereits im ersten Teil des Artikels angesehen und darüber hinaus ist es auch gar nicht nötig sich so viel Mühe zu machen, denn es gibt einfachere Mittel, um eine richtig hilfreiche Dokumentation zu schreiben und daraus folgt die letzte Regel für eine gelungene Dokumentation:

Regel 3: Gib gute Erklärungen und Beispiele
Es liegt in der Natur des Menschen Zusammenhänge verstehen zu wollen und Gegebenes nicht hinzunehmen, ohne es verstehen zu können. Wenn wir nicht nachvollziehen können, was wir lesen, beginnen wir zu zweifeln, hinterfragen und suchen manchmal auch nach Alternativen, weil uns das Vertrauen in das Geschriebene fehlt. All das wollen wir mit einer Dokumentation nicht erreichen. Vermeiden lässt es sich, indem aussagekräftige Erklärungen und Beispiel eingesetzt werden.

Warum wurde sich für Framework A anstelle von B entschieden? Was ist der Grund dafür, dass die Namenskonventionen für die Datenbanktabellen Snake-Case, in allen darüber gelagerten Schichten aber PascalCase vorschreiben? Eine gute Erklärung wird es in beiden Fällen den Entwicklern einfacher machen, den Sinn zu verstehen und das Wissen in der Praxis anzuwenden.

Werfen wir zuletzt noch einmal einen Blick auf den dritten Punkt im obigen Dokumentationsbeispiel zur Internationalisierung: die Informationen bezüglich der Browsersprache, sind in zweierlei Hinsicht sehr wertvoll. Zunächst ist die Erwähnung selbst wichtig, da sie zeigt, dass es durchaus in Erwägung gezogen wurde, mit der Browsersprache zu arbeiten. Ohne diese Information, könnten andere Entwickler mutmaßen, es wäre übersehen worden und eine neue, gut gemeinte aber falsche Optimierung ins Spiel bringen. Warum das falsch wäre, geht aus der ergänzten Erklärung in Bezug auf das Versprechen an die Benutzer hervor. Gäbe es diese Erklärung nicht, das heißt würde dort nur stehen „Die Browsersprache wird ignoriert“, wäre das zwar immer noch eine klare Aussage, die aber Fragen offenlässt und dadurch möglicherweise in der Praxis nicht adäquat umgesetzt wird. Darüber hinaus ist eine solche Festlegung ja auch nicht in Stein gemeißelt und könnte irgendwann wieder in Frage gestellt werden. Bei der Abwägung einer solchen Entscheidung wäre die ursprüngliche Absicht logischerweise die wichtigste Entscheidungsgrundlage.

Mit der Dokumentation im Team arbeiten

Dokumentation ist kein Selbstläufer, sondern ein Produkt disziplinierter Arbeit. Damit ein Unternehmen von ihrem Potential profitieren kann, braucht es einige Mühe bis die Teamkultur so weit gereift ist, dass ein lebendiger Dokumentationsprozess entstanden ist. Wichtigste Voraussetzung dafür: alle Mitglieder des Teams müssen verstanden haben, worin der Mehrwert von Dokumentation besteht, wie bereits im ersten Teil des Artikels erläutert wurde. Und weil beim Dokumentieren die Erfolgserlebnisse sehr viel seltener sind, als beim Programmieren, ist es wichtig, dass wir uns regelmäßig gegenseitig daran erinnern und gleichzeitig eine hohe Wertschätzung für die Dokumentationsarbeit einander entgegenbringen.

Eine Dokumentation muss natürlich ständig auf dem aktuellen Stand gehalten werden und das sollte – wie wir bereits gesehen haben – möglichst zeitnah erledigt werden. Es ist Teil der Entwicklungsarbeit und warum also nicht gleich in den regulären Review-Prozess integrieren? Kollegen, die im Moment des Reviews in der Regel nicht in gleicher Weise mit dem Sachverhalt vertraut sind, wie der verantwortliche Entwickler, schauen mit einer anderen Perspektive auf die Dokumentation. Dadurch fallen Lücken oder auch nebensächliche, aufgeblähte Informationen schnell auf und es kann unkompliziert noch einmal nachgebessert werden.

Das führt uns zu einem wichtigen Aspekt, der gerne vergessen wird: Dokumentationsarbeit besteht nicht nur darin neue Informationen zusammen zu tragen oder Bestehendes zu aktualisieren, sondern auch Veraltetes zu entfernen. Das erfordert genauso wie bei obsolet gewordenem Code manchmal eine gewisse Disziplin, denn etwas zu löschen, für das wir viel Schweiß und Mühe investiert haben, fällt uns nicht leicht. Bewusst oder unterbewusst fragen wir uns: ja, aber wenn wir es doch noch einmal benötigen? Dann gibt es das Source Control oder eine andere Form der Historisierung. Informationen, die keinen Mehrwert mehr stiften, sollten entfernt werden, denn ihr weitere Existenz kostet anderen Kollegen Zeit, wenn sie sich auf der Suche nach Antworten mit diesen nutzlosen Inhalten auseinandersetzen. Im schlechtesten Fall können dadurch auch Falschinformationen weiterverarbeitet werden, die zu falschen Ergebnissen in der Entwicklung führen.

Doch auch wenn währen der Entwicklung konsequent dokumentiert und im Review geprüft wird, genügt das noch nicht ganz, denn eine Dokumentation ist in der Regel nie „fertig“. Es geschieht trotz Prozess immer wieder, dass Dokumentation veraltet oder lückenhaft ist. Das gesamte Team muss daher konsequent an seiner Aktualität und Vollständigkeit arbeiten, wofür jedes Teammitglied in der Verantwortung steht. Wer feststellt, dass er trotz Dokumentation recherchieren oder nachfragen musste, ist in der Pflicht, sich darum zu kümmern, dass die fehlenden Informationen ergänzt werden, völlig unabhängig davon ob er Urheber der Dokumentation ist. Selbiges gilt für falsche oder überflüssige Informationen. Eine „Kümmerkultur“, die vom gesamten Team gelebt wird, ist extrem wichtig, um dauerhaft erfolgreich mit der Dokumentation zu arbeiten.

Dokumentation muss auch gelesen werden

Nachdem wir nun lange über die Entstehung von Dokumentation gesprochen haben, sollten wir auch noch über das sprechen, was auf den ersten Blick selbstverständlich erscheint: Das Lesen also Nutzen der Dokumentation. Das ist nämlich im Alltag nicht immer eine Selbstverständlichkeit, denn schließlich ist es bequemer einer Kollegin eine Frage zu stellen und sofort eine Antwort zu erhalten anstatt sich auf die Suche nach einer Antwort in der Dokumentation zu machen. Es ist aber ziemlich ineffizient, wenn die Kollegin, nach ihrer Zeit, die sie bereits für die Dokumentation investiert hat, jetzt noch einmal Zeit für die persönliche Erklärung an einen Kollegen investiert.

Man könnte damit argumentieren, dass die Suche nach der Information gegenüber dem persönlichen Gespräch deutlich mehr Zeit kostet. Das ist bezogen auf die absolute Dauer richtig, doch die Zeit, die wir mit der Dokumentation verbringen ist keinesfalls vergeudete Zeit. Damit sie ihren echten Wert entfalten kann, müssen wir regelmäßig mit ihr arbeiten, anstatt sie nur quartalsweise als Nachschlagewerk zu verwenden. Während wir dort nach Informationen suchen, nehmen wir tiefgreifendes und wertvolles Expertenwissen auf, was unseren eigenen Wissensschatz kontinuierlich erweitert. Es ist also keinesfalls unhöflich in der Antwort auf eine Frage freundlich auf die vorhandene Dokumentation zu verweisen, sondern dient in diesem Moment sowohl Fragesteller als auch Antwortgeber.

Fazit

Sofort, kurz gefasst in Aufzählungspunkten und mit ausreichend Erklärungen bzw. Beispielen zu dokumentieren, das sind die Regeln, mit denen sich die Behäbigkeit in der Schreibarbeit überwinden und gleichzeitig bessere Dokumentationsergebnisse erzielen lassen. Wird das in die Entwicklungsprozesse integriert und vom gesamten Team verantwortungsbewusst mitgetragen, braucht es wie für alles in unserem Beruf nur noch eines: eine gute Portion Disziplin.