Wie vermeiden Sie, dass die Serverdokumentation nicht mehr mit dem eigentlichen Setup synchronisiert wird?

Wir haben eine einigermaßen gute Dokumentation für unsere Umgebung (im AsciiDoc-Format), die es kürzlich einer anderen Person ermöglichte, das gesamte Setup in weniger als 30 Minuten von Grund auf neu zu erstellen.
Ich habe jedoch festgestellt, dass nach der Ersteinrichtung leicht kleine Änderungen am System vorgenommen werden (z. B. inetd wird deaktiviert, mein IMAP-Server überwacht einen zusätzlichen Port für ManageSieve-Verbindungen, ein neuer Router wird zur Exim-Konfiguration hinzugefügt) Nicht sofort in der Dokumentation landen (wenn überhaupt).

Meine Idee war , dieses Problem durch die (teilweise?) Zu vermeiden Erzeugung der Dokumentation aus den Konfigurationsdateien und die Kommentare darin - ein Weg , dies gesetzt sein , um zu implementieren /etcund /usr/local/etcin eine Quellcode - Management - System (sagen - git) und dann ein Lauf Skript, das die Dokumentation bei jedem Commit neu generiert. Ich bin mir jedoch nicht sicher, ob dies übertrieben und / oder zu schwierig wäre, um es richtig zu machen (schließlich möchte ich keine vollständigen Kopien der Quelldateien in meiner Dokumentation, sondern nur die Unterschiede).

Wie vermeiden andere Personen, dass die Serverdokumentation veraltet ist? Gibt es eine gute Möglichkeit, sie automatisch synchron zu halten, oder haben Sie nur die Disziplin, die Dokumentation zu aktualisieren, wenn Sie das System ändern?

Sie werden nie von einer Dokumentation loskommen, aber wie Sie angedeutet haben, gibt es Systeme, die in Ihren Änderungsprozess integriert werden können, um einen Großteil davon abzudecken.

• Verwenden Sie ein Konfigurationsverwaltungstool (wie Marionette oder Koch ).
• Speichern Sie Ihre Konfiguration änderungsgesteuert. (wie Git oder SVN )
• Stellen Sie sicher, dass die Konfiguration für Menschen lesbar / zugänglich ist (dh Klartext, durchsuchbare Datenbank).

Auf diese Weise wird die Dokumentation auf niedrigerer Ebene, die wir normalerweise alle vermissen (oder nicht bearbeiten), durch Speichern dieser Bereitstellungsinformationen in Konfigurationselementen oder Code als Teil des Systems erzwungen, an dem Sie Änderungen vornehmen. Dies hat auch einen zusätzlichen Vorteil, dass der Prozess in Zukunft wiederholbarer wird.

Die externe Dokumentation muss noch aktualisiert werden, wird jedoch mit Zeigern auf "x bereitstellen" oder "y bereitstellen" anstelle langer Befehls- / Dateilisten sehr hoch. Dies macht Dokumentationsänderungen außerdem weniger häufig und einfacher, was auch bedeutet, dass es wahrscheinlicher ist, dass sie durchgeführt werden.

Auch bevor Sie nach Hause gehen, hat jemand mit Puppe wahrscheinlich schon etwas geschrieben , um zu verwalten, was Sie wollen.

Wenn Sie nur ein oder zwei kleine Systeme verwalten, scheint es ein Overkill zu sein, ein großes Konfigurationsmanagementsystem wie Puppet oder Chef einzurichten. (Wenn Sie in Zukunft mehr Systeme haben möchten, tun Sie dies jetzt!)

Für ein kleines Setup wie dieses würde ich empfehlen etckeeper, ein Programm zu verwenden, das /etcin ein gitRepository gestellt wird und einige nützliche Funktionen bietet, z. B. ein automatisches Commit, wenn Sie ein Paket installieren, aktualisieren oder entfernen.

Sie müssen Ihre Dokumentation nur jedes Mal aktualisieren, wenn Sie Änderungen am System vornehmen. AKA Change Management.

Die Tatsache, dass die meisten Unternehmen das Änderungsmanagement so lächerlich implementieren, dass es schlimmer als nichts wird, sollte die Nützlichkeit des Grundkonzepts nicht beeinträchtigen oder Sie daran hindern, es richtig zu machen.

Ich habe früher htmleine Art Wiki verwendet, um alle meine Konfigurationen zu verfolgen. Jetzt arbeite ich in einem Windows-Shop mit ( schauderndem ) SharePoint. Jetzt verwende ich Word-Dokument- "Vorlagen", die ich erstellt habe, um jedes System und jede von mir vorgenommene Konfigurationsänderung zu verfolgen, was angesichts der vielen nicht so schlimm ist, wie es sich anhört Systeme sind nur Ausstechkopien anderer, die alle in einem Dokument zusammengefasst werden können. (Und ich behalte lokale Kopien aller meiner Dokumente auf meiner Festplatte, die tatsächlich vernünftig organisiert sind, und werfe sie auf den unorganisierten Heap, der die SharePoint-Website eines anderen ist.)

Die größte Herausforderung besteht darin, die Zeit für die Dokumentation zu nutzen. Dazu füge ich die Dokumentationszeit als Teil der Zeit für die Änderung hinzu. Also nicht wirklich so schwer, besonders wenn du ein bisschen wie ein Arsch bist und es dir nichts ausmacht, den Leuten zu sagen, sie sollen abhauen und in der Schlange stehen, weil du im Moment zu beschäftigt für ihr Problem bist.