Konfiguration und Dokumentation

Fällt mir bei der Fehlersuche oder normalen Administrationsarbeit eine merkwürdige Konfiguration auf, frage ich mich oft, warum das so und nicht anders konfiguriert wurde und ob ich es nicht umkonfigurieren sollte. Bei der Fehlersuche ist der Drang groß, das dann "korrekt" zu konfigurieren, insbesondere, wenn der Fehler dadurch behoben ist.

Aber gerade wenn diese Konfiguration schon längere Zeit so bestand, während der Fehler erst seit kurzem auftrat, muss ich mich natürlich fragen, welchem Zweck diese Konfiguration diente? Das Problem verlagert sich dann von der reinen Fehlersuche nach der Frage der Intention, die mit dieser - scheinbar fehlerhaften - Konfiguration verfolgt wurde.

Praktisch ist dann wenn ich auf eine gut gepflegte Dokumentation zugreifen kann, die nicht nur das faktisch Konfigurierte sondern auch die Gründe für diese Konfiguration dokumentiert.

Ganz abgesehen davon, dass ich das Warum von Entscheidungen bisher nur in wenigen Fällen dokumentiert vorfand, gibt es das Problem, dass die Anforderungen an ein System sich im Laufe der Zeit ändern. Und selbst wenn anfänglich die Gründe für bestimmte Entscheidungen dokumentiert waren, so werden die Gründe für Änderungen, meist an anderer Stelle dokumentiert oder gar nicht.

So divergiert auch eine vorbildliche Dokumentation im Laufe der Zeit immer mehr von der tatsächlichen Konfiguration.

Eine Ursache dafür ist, dass die Pflege der Dokumentation neben der eigentlichen Konfiguration, doppelte Arbeit ist, und wenn überhaupt ausgeführt, nicht immer mit der Realität übereinstimmt. Besser ist, wenn es auch hier eine single source of truth gäbe.

Dafür habe ich mehrere Möglichkeiten:

Ich generiere die Konfiguration aus der Dokumentation,
oder ich generiere die Dokumentation aus der Konfiguration.

Konfiguration aus der Dokumentation generieren

Die Konfiguration aus der Dokumentation zu generieren, hat den Vorteil, dass die Dokumentation umfangreicher sein kann und auch das Warum, also die Intention und Randbedingungen, enthalten kann. Für die Konfiguration zieht man nur das heraus, was die Maschine braucht.

Nachteilig ist hier allerdings, dass sich ad-hoc-Konfiguration verbietet, wenn sie nicht auf schnellstem Wege in der Dokumentation abgebildet wird und anschließend eine neue "offizielle" Konfiguration generiert wird.

Außerdem ergibt sich das Problem, wie man aus einer für "normale" Menschen verständlichen Dokumentation, eine für Maschinen lesbare Konfiguration generiert. Dafür gibt es jedoch bereits Lösungen, in der Softwareentwicklung zum Beispiel Literate Programming, dass sich in angepasster Form auch für die Konfiguration anwenden lässt.

Dokumentation aus der Konfiguration generieren

Dieser Ansatz hat den Vorteil, dass die Dokumentation immer die vorhandene Konfiguration abbildet.

Ein Nachteil ist jedoch, dass Meta-Informationen, wie Intention und Randbedingungen, normalerweise nicht aus der Konfiguration herausgelesen werden können. Diese sind dann nicht vorhanden, oder müssen extra gepflegt werden, was dem Prinzip single source of truth widerspricht.

Für den Fall, dass die Konfiguration Freitextkommentare zulässt, lassen sich die fehlenden Informationen eventuell darin unterbringen.

Kombination beider Varianten

Beide Möglichkeiten zu kombinieren, erlaubt die Intention und Randbedingungen relativ einfach zu dokumentieren und die tatsächliche mit der gewollten Konfiguration am Ende zu vergleichen.

Wie gehe ich dazu vor?

Ich sichere die aktuelle Konfiguration sowieso regelmäßig. Ad-hoc-Konfigurationen sind an der Tagesordnung.
Ich installiere ein System, dass mir die gewünschte Konfiguration aus der vollständigen Dokumentation generiert und installiert.
Ich kontrolliere regelmäßig automatisch, ob die generierte Konfiguration mit der gesicherten übereinstimmt. Bei einer ad-hoc-Konfiguration ergibt sich eine Abweichung und ich werde darauf aufmerksam gemacht.

Jenachdem, wie schnell ich die Dokumentation nachführen kann und wie wichtig die ad-hoc-Konfiguration ist, schalte ich das automatische Ausbringen der Konfiguration dann ab, bis die Änderung in der Dokumentation nachgeführt ist.

Das birgt allerdings die Gefahr, das Dokumentation und Konfiguration wieder auseinanderlaufen, wenn es ständig abgeschaltet ist. Ohne einen sinnvollen Prozess dafür funktioniert es nicht.