Blog

Sollte ich das dokumentieren?

Dokumentation – ein gern vermiedenes Thema unter Software-Entwicklern, denen natürliche Sprache berufsbedingt nicht immer formell genug ist – „Wenn du wissen willst, wie es funktioniert, schau halt in den Code“. Theoretisch vielleicht richtig, denn wie die Anwendung funktioniert, ist dort eindeutig nachvollziehbar. Trotzdem nicht ausreichend, denn die Intention dahinter, die zugrundeliegenden Entscheidungen und eventuelle Implikationen oder verworfene Alternativen findet man dort nicht.

Wenn man überlegt, wie Software-Dokumentation im Alltag üblicherweise entsteht, kann man durchaus nachvollziehen, warum mancher Entwickler sie eher dünn hält. (Dabei sollte erwähnt sein, dass ich in hier von einem im weitesten Sinne agilen Entwicklungsprozess ausgehe – eine umfangreiche Vorab-Dokumentation, vom Elfenbeinturm aus diktiert und in Steintafeln festgehalten wäre nichts, worüber ich hier schreiben wollen würde.) Wenn ich nun also als agil arbeitender Entwickler ein neues Feature gebaut habe oder ein größeres Refactoring durchgeführt habe, stelle ich mir die Frage: „Sollte ich diese Änderung dokumentieren?“.

Zweifelsfrei keine einfache Frage. Wer kann schon ahnen, welche (womöglich zukünftigen) Beteiligten mit welchem Vorwissen diese Dokumentation zu welchem Zeitpunkt und in welchem Kontext lesen werden? Eine ernsthafte Beantwortung all dieser Fragen ist leider unmöglich. Man wird nie im Vorhinein sichergehen können, dass man immer exakt das richtige und nichts darüber hinaus dokumentiert. Irgendwie müssen nun wenigstens einige Entwickler die Ausgangsfrage aber doch beantworten, sonst würde ja in keinem Projekt eine Dokumentation existieren. Aber wie kommen sie zu dieser Antwort?

Entscheidungsfindung – leicht gemacht

Hier kann ein Blick aus der psychologischen Perspektive helfen. Ich bin der festen Überzeugung, dass in einer Vielzahl der Fälle eine Urteilsheuristik greift. Dabei wird unbewusst eine schwierige Entscheidung durch eine einfachere ersetzt. In diesem Fall könnte die einfachere Frage etwas sein wie „Habe ich gerade Lust darauf, diese Änderung zu dokumentieren?“. Leider fatal, denn diese Frage wäre genau so hilfreich wie schwierig zu beantworten: nicht besonders.

Was also tun, damit diese unbewusste Ersetzung nicht mehr stattfindet? Ich persönlich versuche mir die Ersetzung bewusst zu machen und mir bessere einfache Fragen zu überlegen, die ich stattdessen beantworte:

  • „Wenn ich neu in das Projekt käme, würde ich darüber lesen wollen?“
  • „Würde ich die Änderung einem unerfahrenen Team-Kollegen erklären müssen?“
  • „Wenn ich jetzt in den Urlaub fahre, wäre es kritisch, wenn niemand im Team darüber Bescheid wüsste?“
  • „Wenn ich (als Berater) das Projekt verlasse, sollte dieses Wissen konserviert sein?“
  • „Halte ich es für wahrscheinlich, dass es für andere Teams wichtig oder nützlich wäre?“

Die Liste ist nicht vollständig, aber das sind einige der Fragen, die ich mir in der Vergangenheit gestellt habe und die mich dazu gebracht haben, Dinge zu Dokumentieren. Sie haben auch alle gemein, dass es immer eine oder mehrere Personen gibt, in die man sich hinein versetzen kann – genau den/diejenigen für wen die Dokumentation dann gedacht wäre. Das macht nicht nur die Entscheidung einfacher, ob man etwas schreiben sollte, es macht auch das Schreiben selbst einfacher, weil man eine gute Vorstellung davon hat, für wen man eigentlich schreibt.

Titelbild: neONBRAND/unsplash.com

Holisticon AG — Teile diesen Artikel

Über den Autor

Entwickler mit Vorliebe für FOSS. Versucht den Blick für das Wesentliche zu behalten, immer auf der Suche nach neuen Herausforderungen.

Antwort hinterlassen