Ich wurde mit der Einrichtung und Verwaltung einer brandneuen Laborumgebung beauftragt, die aus vielen Maschinen mit unterschiedlichen Rollen besteht. Es gibt einen VM-Host, mehrere Webserver, mehrere Datenbankserver und so weiter.
Es gibt sehr spezielle Anforderungen und Prozesse, die als Teil dieser Laborumgebung dokumentiert werden müssen. Wir möchten beispielsweise keine automatischen Windows-Updates aktivieren und es gibt viele Überlegungen, die wir festhalten möchten, um sie den verschiedenen Parteien (Führungskräften, Managern, Entwicklern, IT-Managern, Leuten aus der Qualitätssicherung) zu erklären.
Während ich die Einrichtung durchführe, möchte ich diese Gespräche unbedingt in einer Art formellem Dokument festhalten. Ich wollte einfach ein Word-Dokument erstellen und jede Serverrolle in mehrere separate Abschnitte unterteilen:
- Zusammenfassung
- Wartungsbedarf
- Inventarisierung der installierten Software
- Verfügbare Hardware
- Hardware-Standardeinstellungen
Ich wüsste gern, ob es bessere Vorlagen gibt, an die ich mich beim Erstellen der Dokumentation für diese Maschinen halten kann. Ich hoffe, dass das, was ich letztendlich erstelle, gut genug ist, damit jemand anders die Maschinen bei Bedarf nachbauen kann.
Antwort1
Die wichtigsten Dinge für ein gutes Dokumentationssystem sind:
- Einfach zu aktualisieren (oder die Leute aktualisieren es nicht, was es schlimmer als nutzlos macht)
- Einfacher Zugriff – von jedem Standort und von mehreren Geräten aus.
- Gut organisiert – die Benutzer können die benötigten Informationen leicht finden und es kommt nur zu minimalen Duplikaten derselben Informationen.
Ich habe es mit Word-Dokumenten versucht. Sie schlagen in allen drei Punkten fehl. Word-Dokumente sind schwer zu aktualisieren, am Ende haben die Leute unterschiedliche Kopien usw.
Das beste System, das ich für meinen Bedarf gefunden habe, ist ein Wiki. DokuWiki funktioniert für meine Zwecke ganz gut. Ich kann von überall aus problemlos darauf zugreifen und es aktualisieren.
Ich habe mein Wiki mit Seiten angelegt, die die gesamte Netzwerkkonfiguration beschreiben und auf Seiten für jeden Server, Cluster und jede Anwendung verweisen. Auf diese Weise werden alle Details zu einem bestimmten Element auf separaten Seiten gespeichert und können von jedem relevanten Ort aus verlinkt werden. Wenn sich etwas ändert, muss ich es nur auf einer Seite ändern und kann die gesuchten Informationen leicht finden.
Sie können damit auch Namespace-Vorlagen angeben, sodass beim Erstellen einer neuen Serverseite diese bereits mit Tabellen zum Eingeben von IP-Adressen, Hardwarekonfigurationen usw. ausgefüllt ist. In allen leeren Feldern steht FIXME, sodass ich das gesamte Wiki nach FIXME durchsuchen und sehen kann, was in der Dokumentation fehlt.
Wenn Sie es wirklich ausgefallener haben möchten, können Sie Plugins schreiben, die Dinge wie Konfigurationsdateien übernehmen, sie analysieren und in einem leicht lesbaren Format anzeigen. Ich habe beispielsweise ein Plugin namens PatchPanel geschrieben, das eine Textbeschreibung eines Netzwerk-Patchpanels übernimmt und ein Bild davon mit Beschriftungen für die einzelnen Ports zeichnet.
http://blog.emsley.ca/2014/04/documentation.htmlenthält eine ausführlichere Beschreibung meiner Einrichtung (Haftungsausschluss: Link zu meinem Blog, allerdings völlig zum Thema).