Heute mal was ganz anderes. Liegt mir gerade auf dem Herzen.

Lasst uns über Dokumentation in Projekten und beim späteren Betrieb der Lösung sprechen. Hey, jetzt nicht gleich umschalten. :-)

Über Dokumentation spricht keiner gerne. Sie hat den Ruf, dass das Erstellen meist im Weg steht und als lästige Pflicht gesehen wird. Klar wird jeder sofort den Nutzen einer Dokumentation nicht in Frage stellen wollen, dennoch ist sie das Stiefkind vieler Projekte.

Woran liegt das?

Meine These dazu ist, dass das Dokumentieren von Lösungen als so unangenehm wahrgenommen wird, weil vielen einfach nicht immer wirklich klar ist, was denn nun wie dokumentiert werden muss. Vorlagen existieren meist nur bei großen Organisationsstrukturen wie Konzernen und Behörden oder zertifizierten Spezialisten und oft sind diese Vorlagen dann doch nicht mit der Praxis wirklich kompatibel und führen zu mehr Verwirrung als, dass sie helfen. Es kommt Ende meist wieder auf die Kreativität des Einzelnen an.

Natürlich gibt es noch das Versprechen der Dokumentationsgeneratoren. Auch ich verwende gern solche automatisierten Tools, um eine Microsoft Business Intelligence Lösung zu "dokumentieren". Meist auf Basis der Analysis Management Objects entwickle ich kleine Helfer, welche dann entsprechende Repositories verwalten. Nur, ist das wirklich Dokumentation? Die gleiche Frage stellt sich mir bei vielen IT-Infrastruktur Visualisierungstools. Schicke Poster. Wo ist der konkrete Nutzen?

Stellen wir uns mal die total esoterische Frage: Was ist überhaupt der ganz konkrete Nutzen von Dokumentation ?

Hey, wer hat da gelacht?

Ich glaube, dass gerade diese Frage bzw. die Tatsache, dass sie häufig nicht spontan und konkret beantwortet werden kann, das primäre Problem bei der Erstellung einer (nützlichen) Dokumentation ist. Weil wenn immer klar wäre, was denn nun in einer Dokumentation erwartet werden würde, dann würde vielen armen Seelen die Erstellung einer solchen wesentlich leichter fallen.

Also, was ist der konkrete Nutzen einer Dokumentation? Wozu braucht man so etwas überhaupt?

Nein, so klar ist das nämlich gar nicht! Die Antwort kann nicht lauten: Um zu dokumentieren. :-)

Eine Dokumentation soll ja etwas bewirken können. Eine Wirksamkeit haben. Und zwar, wenn etwas geändert werden muss bzw. wenn etwas schief geht. Natürlich wird das nie im gerade aktuellem Projekt passieren. Also, dass jemand was ändern möchte. Später. oder dass gar etwas schief geht. Versprochen.

Nennen wir diese möglichen Einsatzzwecke einer Dokumentation doch einfach mal Risiken. Für mich sind die Folgen einer Änderung oder der Problemfall zukünftige Risiken, welche wir heute bereits verwalten müssen. Wir müssen Maßnahmen ergreifen, um diese Risiken zu minimieren. Und schwupps sind wir beim Risikomanagement angekommen.

Wie steht es bei Wikipedia so schön: "Risikomanagement umfasst sämtliche Maßnahmen zur systematischen Erkennung, Analyse, Bewertung, Überwachung und Kontrolle von Risiken."

Risikomanagement hat nichts mit Schwarzmalerei zu tun. Ganz im Gegenteil. Es ist für mich eine erstrebenswerte Form von Komfort im Projekt und auch gerade für den späteren Betrieb als auch weitere Anpassungen. Und idealerweise das alles nicht durch mich. Womit wir bei einem weiteren Risiko wären: Der ehemalige Berater ist aus welchen Gründen auch immer nicht verfügbar bzw. kann sich an nichts mehr erinnern. Welche Risiken entstehen dadurch und müssen durch welche Maßnahmen verhindert werden?

Eine verwandte Disziplin zur Dokumentation ist das sogenannte Betriebshandbuch. Hier ist der spätere Nutzen bereits im Namen dokumentiert. (Kleines Wortspiel. öhm. )

Zurück zur Dokumentation. Ich möchte hier jetzt keine x-te Vorlage für eine gute Dokumentation liefern. Vielmehr den Ansatz, dass sich bei der Planung und Erstellung einer Dokumentation erst mal bewusst gemacht werden muss, welche möglichen Risiken damit verringert bzw. verhindert werden sollen.

Beispiel. Klar soll eine Dokumentation eines Stück Codes helfen, dass er einfacher geändert werden kann. Nur das ist NICHT der eigentlich Nutzen. Der Nutzen ist, dass

a.) die Änderung schneller, einfacher und damit günstiger wird. (Risiko der Kosten)

b.) und, dass sie ohne unvorhersehbare Folgen für den Betrieb der gesamten Lösung sein wird. (Risiko der Katastrophe.)

Es ist zu einfach jetzt zu sagen, dass das doch klar ist. Vielmehr ist es so, dass gerade das Spiegeln von möglichen Risiken an den notwendigen Maßnahmen die Erstellung einer wirksamen Dokumentation deutlich vereinfacht. Des Weiteren wird die Pflege einer Dokumentation deutlich vereinfacht, weil "das Thema" klar ist. Wer kennt nicht noch die Aufsätze von früher mit dem Hinweis "Thema verfehlt."?

Jeder Teil einer wie immer gearteten Dokumentation sollte helfen Risiken zu minimieren. Da hat auch das IT-Poster seinen Sinn, da man sich schnell einen Überblick verschaffen kann (Spart Einarbeitungszeit) und das SQL Server BI Tool hilft die Details im Auge zu haben.

Also stellen sich beim Erstellen einer guten Dokumentation die Fragen nach dem WAS? und dem WIE? soll etwas dokumentiert werden, damit möglichst viele Risiken ausgeschlossen werden können.

Hoffe, dass diese paar Zeilen dem einen oder anderem helfen werden, um eine Dokumentation wirksamer und einfacher zu erstellen.