Doku ist für’n A….!

Neben der Aussage, dass man ausgiebig testen müsse, ist die Ansage, dass man alles und jeden dokumentieren muss wohl das Mantra, dass man als Programmierer am häufigsten zu hören bekommt. Schon die Azubis bekommen eingebläut, dass sie gefälligst JavaDoc und Inline-Dokumentation im Quelltext zu verwenden haben, dass es ein ausführliches Benutzer-, Betriebs- und Entwickler-Handbuch geben muss, dass es mal jemand übernehmen kann, falls die Zuständigkeit wechselt.

Alles Blödsinn!

Den Quelltext zu dokumentieren erachte ich ja noch als sinnvoll. Auch ich hab schon nach wenigen Monaten vor den Trümmern meiner Programme gestanden und Fragezeichen im Gesicht gehabt, was ich da warum und wie programmiert habe. Eine Zeile Doku und das ganze wäre schon viel einfacher zu verstehen gewesen. Aber sowas nennt sich wohl Arbeitsplatzsicherungsmaßnahme.

Frustrierender wird es dann wenn die Doku nach extern geht.

Man gibt sich bei den Handbücher, speziell für Benutzer, schon sehr viel Mühe. Und mit Mühe meine ich: Man stellt sich dumm, verdammt dumm. So dumm, dass man sich manchmal schon fast einen Buntstift in die Nase schieben möchte um eine absolut idiotensichere Dokumentation abzuliefern.

Dummerweise kann man sich noch so dumm stellen: Idiotensicher gibt es nicht! Es findet sich immer noch jemand der den Limbo unter dem Niveau des Schriftstücks durch schafft… oder auch einfach vorbei geht.

Offen und ehrlich sind dann zumindest Aussagen wie:

Das Handbuch habe ich nicht gelesen. Das war ja so viel…

Es waren vielleicht zehn Seiten. Das Programm war auch nicht so wirklich anspruchsvoll und es wurde im Grunde nur erklärt, was in der Konfigurations-Datei einzustellen ist, bevor man auf den Knopf drückt. So war dann eben das Programm Schuld, dass es nicht klappte, schließlich war ja alles richtig eingestellt, und es wurde ein Außeneinsatz ausgelöst… Beim Kunde, mit diesem Satz. Glückwunsch.

Frustrierender ist es dann, wenn man sich 110 Seiten mit einem wirklich umfangreichen Dokument abplagt, dass sich „Schnittstellenspezifikation“ nennt. 110 Seiten in denen haarklein jedes einzelne Element des Inhalts eines REST-Services aufgedröselt wird. Handgeschrieben! Also schon digital, aber nicht automatisch generiert! Ein armer Entwickler hat dafür sehr sehr sehr viel Zeit geopfert um genau und unumstößlich festzulegen was man darf und was nicht!

Nur liest das keiner…

Mein aktueller Rekord liegt bei fünf RTFM für einen Fehler. Eigentlich kam der Entwickler eines gar nicht mal so kleinen Softwareherstellers mit nur mit einer Frage („Ich glaube, Ihr Beispiel ist falsch…“) und bekam dann ein freundliches fünf RTFM zurück („Stimmt, das Beispiel ist falsch… an der Stelle aber auch egal, weil sie ansonsten noch hier, hier, hier und hier Fehler in Ihrer Anfrage haben, die in der Schnittstellenspezifikation auf folgenden Seiten definiert werden…“).

In solchen Momenten frage ich mich dann, warum ich überhaupt eine Doku schreibe und komme zu dem Schluss:

Weil’s halt dazugehört! Auch wenn’s am Ende keiner liest!