Dokumentation

Es kommt der Zeitpunkt, an dem etwas nicht mehr geht. Und dann sind sie froh, wenn es ein Stück Papier oder eine Textdatei gibt, in der die hoffentlich aktuellen Einstellungen hinterlegt sind. Wie kann man Exchange dokumentieren ?.

Zu viele Personen glauben, dass eine Dokumentation immer den Charakter eines "Buchs" haben muss, was möglichst "perfekt" aussehen sollte. Dies ist ein hoffnungsloses Unterfangen. Ich merke das schon, wenn ich als Autor meines Buchs (Exchange 2003 - Ein Buch zum Thema) hier "aktuell" bleiben will.

Was muss eine Dokumentation bieten ?

Eine Dokumentation in einer Firma zeichnet sich dadurch aus, dass idealerweise mehrere Personen ihren Teil eigenständig dokumentieren. Das stellt natürlich an die Organisation der Dokumentation einige Anforderungen:

Eine Lösung muss daher eine ganz anderen Ansatz wählen als ein Consultant, der ein Word-Dokument mit Deckblatt, Inhaltsverzeichnis etc. erstellt und am Ende "abgibt".

Wie kann ich beginnen ?

Dabei hat Dokumentation erst mal nichts mit "Prozess Management" zu tun und bedeutet auch nicht den Einsatz einer bestimmten Software. Für die Dokumentation sehe ich vier Schritte:

  1. Geeignete Plattform
    Eine Doc-Datei ist vielleicht nicht geeignet. Aber vielleicht ist ein "WIKI" (Wiki) als Ansatz. Denkbar ist aber auch Sharepoint oder eine Sammlung von OneNote-Dateien
  2. Kleine verlinkte Artikel
    Jedes Thema sollte dabei eine eigene Seite sein, die autark editiert und versioniert werden kann und sehr einfach mit anderen Seiten verknüpfbar ist. Bei einem WIKI gibt es z.B. keine feste "Struktur" sondern nur Schlüsselworte und Links. Wenn wirs genau überlegen, dann suchen wir schneller in Google als in einem Inhaltsverzeichnis eines großen Buchs.
  3. Ein Anfang machen
    Dann muss natürlich überhaupt erst mal ein Start gemacht werden. Da interne Mitarbeiter hier fast immer zu wenig Zeit dazu haben, bietet sich hier an, dass z.B. externe Mitarbeiter einzelne Themen einfach dokumentieren, wie Sie es sehen. Dann starten die eigenen Administratoren nicht mit einem leeren Blatt und nebenbei bekommen Sie auch eine dritte Meinung
  4. Mitarbeiter müssen wollen
    Eine Dokumentation lebt, d.h. die eigenen Mitarbeiter müssen die Dokumentation nicht als Pflicht, sondern als unentbehrliches Hilfsmittel akzeptieren und selbst ihren Bereich weiter pflegen.
  5. Integration schaffen
    Wenn es wünschenswert ist, kann man natürlich eine Kopplung schaffen, z.B. dass ein Script die Konfiguration eines Servers ausliest und im Serverdokument mit ablegt.

Sicher wird nicht alles in diesem System landen. Strukturierte Daten einer Softwareverteilung haben dort nichts verloren, sondern bleiben im jeweiligen System. Auch Eventlogs und andere Datenquellen sind viel zu kurzlebig. Aber wenn jemand Arbeit für etwas aufwendet, dann sollte das auch protokolliert werden. Wobei hier zu prüfen ist, ob das wirklich auch mit in die "Doku" muss, oder ein einfaches Tätigkeitsprotokoll nicht ausreichend ist.

Wir bei Net at Work dokumentieren sehr intensiv z.B. mit Supportanrufen oder über Arbeitsberichte. Wir müssen das nicht nur zwecks Rechnungsstellung tun, sondern dies hilft uns auch, wenn später Supportanrufe kommen. Keiner von uns kann die Konfiguration aller Kunden aus dem Kopf wissen.

Zur Plattform

Historisch bedingt bin ich ein "Word"-Freund. Ich habe ein Buch (Exchange 2003 - Ein Buch zum Thema) geschrieben und meine Kunden erwarten zurecht eine "Dokumentation", die man auch Drucken kann. Schon daher ist Word oder ein anderes Textverarbeitungsprogramm natürlich erste Wahl.

Persönlich begrüße ich es immer, wenn ein Kunde schon eine Dokumentationsplattform hat, in der ich mich einbinden kann. Denn durch die Arbeit an der MSXFAQ habe ich die Vorteile vieler kleiner Seiten mit Verlinkungen erkannt.

Ein paar Stichworte zu verschiedenen Systemen. Betrachten Sie diese bitte selbst bezüglich:

Eventuell sind für Sie ja noch andere Kriterien wichtig. Überlegen Sie einfach, was Sie von einer Dokumentationsplattform in ihrem Betrieb erwarten. Ausgestattet mit den Kriterien können Sie dann einige Plattformen vergleichen, z.B.

Plattform Bewertung
Dateiserver mit Textverarbeitung (z.B. Word)
Klassische Plattform, die wohl jeder kennt und meist vorhanden ist		  
OneNote
Unstrukturierte Ablage in Büchern, Karteikarten und Reitern. Aber einfache Suche, Offline, Replikation. Sogar Rechter (je Buch).		  
Sharepoint Designer
Damit bearbeite ich meine MSXFAQ. Wer html-Dateien liebt und die Doku wirklich als "Web" betreiben will, kann damit arbeiten		  
CMS, Wiki o.ä.
Ob Sie ihr Wiki oder CMS nun auf Windows mit Sharepoint oder mySQL und einer Wiki-Software betreiben, bleibt ihnen überlassen. Entsprechend unterscheiden Sich aber die Funktionen bezüglich Authentifizierung, Editierbarkeit etc.		  
Blog
Ein Blog ist keine Dokumentation aber ein Anfang, Änderungen zu protokollieren. Ein Blog bietet sehr viel wie Authentifizierung, Zeitangabe, Schlagworte (Tag-Cloud) und Suche und kann ihr Dokumentationssystem begleiten. Viele Admins haben intern mit "Blogs" angefangen.		  
Webseite + Generator
Warum "aufschreiben", wenn das System alles weiß ? Es gibt schon Programme, die eine automatische Dokumentation ihrer Systeme versprechen. Sie können sicherlich ergänzend eingesetzt werden aber ersetzen keine Beschreibung von Konzepten und Arbeitsabläufen.		  

Welche Plattform oder Kombination von Plattformen bei ihnen passt, kann ich ihnen natürlich nicht sagen.

Welche "Dokumentarten" gibt es ?

Wenn Sie selbst noch nicht dokumentieren oder die aktuelle Form nicht mehr verwalten können, dann sollten Sie mit uns über die Umsetzung einer internen Dokumentation sprechen. Wir könnten z.B. mit ihnen die Anforderungen und Wünsche aufnehmen, ein geeignetes System auswählen und installieren und zuletzt je nach ihren Wünschen die aktuelle Umgebung dokumentieren und die Administratoren in die Benutzung einführen. Nicht immer muss alles in einer Dokumentation stecken. Gerade Betreiber trennen gerne Inhalte für verschiedene Zielgruppen ab. Dann könnten eine ganze Menge Dokumentationen:

Titel Zielgruppe Umfang Beschreibung
Produktbeschreibung Kunde 1-2 Seiten

Als Betreiber einer Systemumgebung "verkaufen" sie ihren Kunden ein Produkt. Viele Firmen werden nur genau ein Produkt verkaufen, aber wenn Standard und Enterprise CALs ein Kostenfaktor werden. dann werden wohl auch intern Unterscheidungen stattfinden. Für die verschiedenen Leistungsumfänge sollten Sie dann eigene Beschreibungen bereitstellen, die aber nicht tief technisch sind, sondern eher für Anwender verständlich sind. Vergleichen Sie dies einfach mit den Informationen, die Sie bei den Anbietern von Webpräsenzen (1&1, Strato, HostEurope, etc.) auf der ersten bzw. zweiten Ebene zur den verschiedenen Paketen erhalten.
Leistungsbeschreibung Kunde 10-20 Seiten

Dies entspricht dann etwa dem "Kleingedruckten" nur bezogen auf die Produktleistungen. Hier sollten Sie alle Leistungen aufführen , die das System erbringen kann, d.h. die Sie theoretisch installieren können. Diese Beschreibung kann durchaus auch etwas detaillierter bezüglich der Funktion sein, aber den Leser interessiert hier natürlich nicht, wie das technisch umgesetzt ist. Das sollte auch verborgen bleiben, denn ihre technische Umgebung kann sich ja ändern.

Diese Beschreibung kann durchaus Appetit auf mehr machen, d.h. Funktionen beschreiben, die von ihnen bereit gestellt werden, aber der Kunde vielleicht noch nicht gekauft hat.
Technische Beschreibung Intern und interessierter Kunde (Backstage) 10-20 Seiten

Diese Dokumentation sollte eine ersten Überblick über die Systemumgebung, die Komponenten und Zusammenhänge geben. Sie sollte nicht allzu tief in die Server und Protokolle gehen, sondern die Funktionsblöcke beschreiben.

Diese Dokument ist quasi das Einstiegsdokument für Personen, die sich in die Materie einarbeiten wollen (z.B.: neue Mitarbeiter) oder Services daran anbauen müssen (z.B. Dienstleister bei der Installation von Zusatzprodukten) oder natürlich den Nachbarteams z.B. aus Bereichen wie Telefonanlagen, Netzwerkverkabelung, Firewall etc. einen Einblick zu geben.

Denkbar ist auch, dass diese Information für interessierte Kunden, quasi als "Backstage"-Information zugänglich gemacht wird. Das kann durchaus auch Imagefördernd sein.
Benutzerhandbuch Endanwender 4-8 Seiten Diese Dokumentation sollte dem Anwender eine Einführung in die Nutzung der angebotenen Dienste geben. Wesentlich sind hier die verschiedenen Zugangsdaten und Einstellungen, so diese nicht per Autodiscover ermittelt werden können und etwaige Besonderheiten der Umgebung. Es kann natürlich kein "Handbuch" für Outlook o.ä., sein.
In Firmen hat sich es aber als gute Praxis heraus gestellt, einfache "Aufsteller" zu verteilen, die z.B.: die Hotkeys für den Office Communicator oder wichtige Hyperlinks enthalten.
Kundenhandbuch Kundenadmin
OU-Admin		 ? Sofern die Verwaltung nicht durch Sie selbst erfolgt, sondern anderen Personen "delegiert" wird, sollten diese auch eine entsprechende Dokumentation erhalten, die diese Schritte beschreibt. Das kann die Dokumentation der verschiedenen Arbeitsschritte oder Zugänge sein und weiterführende Informationen zur Dateneingabe enthalten, sofern diese nicht über eine Provisioning-Lösung schon vorgegeben werden.
Ebenfalls ratsam sind hier ein paar Hintergründe zur Funktionsweise, speziell wenn Änderungen nicht sofort aktiv werden oder manuelle Nacharbeiten erforderlich sind.
Technische Dokumentation Intern ? Diese Dokumente beschreiben Server, Systeme und Zusammenhänge sehr detailliert und werden vorlaufend gepflegt. Überlegen Sie mal, ob hierfür nicht ein WIKI oder etwas ähnliches eine geeignete Plattform zur Dokumentation wäre.
Hier stehen sowohl Installationsbeschreibungen und Checklisten aber auch der aktuelle IST-Stand
Operatorhandbuch Intern ? Hier könnten die Tätigkeiten für Operatoren der Serverumgebung niedergelegt sein. Eine Trennung zum "Kundenhandbuch" ist dadurch gegeben, dass Operatoren in der Regel direkt Einfluss auf die Systeme über entsprechende Management Konsolen und Powershell Befehle nehmen können, die bei einem Admin eines Kunden, der nur für "seine Mitarbeiter" zuständig ist, nicht zur Verfügung stehen.

Diese Aufteilung ist nur ein Vorschlag, den Sie natürlich auf ihre individuellen Bedürfnisse anpassen sollten.

Wie könnte eine Struktur aussehen ?

Auch wenn dieser Abschnitt die Verwendung von Word mit DOC-Dateien nahelegt, so sollten Sie sich nicht daran binden. Eine Struktur gibt es in fast jedem normalen Dokumentationssystem (von einem chaotischen Wiki als Wörterbuchersatz abgesehen)

Die Struktur hängt natürlich davon ab, mit welchen Hilfsmitteln Sie ihre Dokumentation verfassen. Nutzen Sie einfach nur einen Satz Textdateien oder doch eher ein Textverarbeitungsprogramm wie Word. Oder ist es mehr in der Form eines Tagebuchs wie ein Blog oder doch webbasiert in einem Content Management System (CMS a la Mambo, Joomla etc.) ?. Wer eine Webseite, eine Word-Dokumentsammlung oder ein CMS einsetzt, braucht eine gewisse Strukturvorgabe

Wie sie auf Backstage vielleicht schon gelesen habe, pflege und verwalte ich die MSXFAQ komplett offline mit dem Sharepoint Designer (SPD) verwalte und dann hoch lade. So könnten Sie natürlich auch eine Dokumentation schreiben, wenn Sie lieber HTML/XML verwenden. Da aber der SPD extra zu lizenzieren ist und die meisten Personen mit Word umgehen können, ist für den internen Einsatz auch das DOC-Format geeignet.

Nun wissen die meisten Administratoren erst mal, dass man Word starten und Texte eingeben kann. Aber die wenigsten Administratoren arbeiten schon aktiv mit Filialdokumenten und Dokumentvorlagen. Aber die Filialdokumente sind der Schlüssel für eine effektive Dokumentation. Wenn Sie es schaffen, jeden Teil in einem eigenen Dokument zu pflegen und über Filialdokumente die Struktur zu bauen, dann kann die komplette Dokumentation sich wie folgt darstellen:

Da jedes Filialdokument eigenständig und ohne weitere Formatierung ist, können Sie jederzeit ein weiteres Masterdokument anlegen und ausgewählte Filialdokumente dort einbinden. Wer also z.B. eine Dokumentation für den Bereich der der Buchhaltung möchte, kann aus dem Filialdokument der Beschreibung und den Dokumenten der Server sich eine individuelle Dokumentation zusammen stellen.

Und wenn jemand z.B. das Dokument "Server3" aktualisiert, weil ein Update oder Servicepack installiert wurde, dann ist die in allen Masterdokumenten die dieses Filialdokument einbinden, auch aktuell.

Die Masterdokumente haben keine Kopie sondern binden nur die Filialdokumente ein. Somit bleiben die Dokumente an sich überschaubar und klein: Office sperrt Dokumente per Menü oder wenn das Filialdokument eigenständig geöffnet wird beim Einsatz über einen Dateiserver. Mehrere Personen können parallel in ihren Dokumenten arbeiten. Allerdings bietet ein Dateiserver keine einfache Möglichkeit einer Versionierung.

Insofern ist allein mit Word, Filialdokumente und einem Dateiserver schon eine sehr effektive Dokumentation mit mehreren Personen möglich, wenn man sich eine passende Struktur von Dokumenten aufbaut, die üblicherweise aber alle im gleichen Verzeichnis abgelegt werden. Da Word die Überschrift als Dateinamen heranzieht und die Umbenennung mühsam ist, sollten sie jedes Filialdokument mit einer eindeutigen aussagekräftigen Überschrift beginnen lassen. Alternativ kann man eine Vorlagendatei kopieren und als neues Dokument einhängen.

Die Aufteilung in einzelne Dokumente ohne weitere Struktur und Formatierung erlaubt sogar die automatische Erstellung. Wer mag könnte also pro Server eine "servername.doc" Datei z.B. per VBScript erstellen lassen und in der Dokumentation einfach einbinden. Sogar Querverweise funktionieren über Dokumente hinweg.

So eine Struktur ist natürlich erforderlich, wenn Sie eben ein statisches System aus Dateien oder eine Webseite mit einem CMS betreiben.

Hilfsmittel Notepad

Das einfachste Hilfsmittel zur Dokumentation ist ein einfacher Texteditor. Zugegeben kann man hier meist keine Bilder einfügen oder Formatieren, aber solche ein Editor findet sich auf wirklich jedem System und ist daher immer "zu Hand". Sie müssen sich natürlich ein Schema zur Benennung und Ablage der Dateien überlegen und die Volltextsuche im Windows Explorer kann bei dem Wiederauffinden schon helfen. Allerdings krankt so ein System, dass es eben "Freitext" ist, d.h. der Admin wird nicht gezwungen, bestimmte Daten auszufüllen (z.B. Datum, Version, Produkt, Server etc)

Dennoch ist gerade "Notepad" ein einfaches und effektives Hilfsmittel verschiedene Änderungen erst mal zu protokollieren. In eine "große Dokumentation" kann man die Infos ja dann am Arbeitsplatz mit einem anderen Produkt immer noch einfließen lassen. Zwei Funktionen von Notepad kennen die wenigsten Admins.

Ich weiß nicht, seit wann es die Funktion schon gibt, aber anscheinend hat da früher jemand schon damit gearbeitet. Selbst in einem Notepad von Windows 98 konnte ich die Funktion finden.

Ein Plädoyer für ein Server-Blog

Ich komme als Consultant mit vielen Firmen in Kontakt und sehe deren "Dokumentation". Für mich ist "dokumentieren" normal und gehört immer zu einem Projekt und sogar zu einem Vorgespräch, auch wenn mit kein Gesetz dazu anhält, wie dies bei Bankberatungen z.B. der Fall ist.

Seit einigen Jahren "bloggt" die Welt über alles mögliche. Ein gutes Beispiel für eine technische Nutzung ist das Exchange Team Blog mit dem Titel "You Had Me At EHLO.. unter der Adresse http://msexchangeteam.com/. Das Exchange Team war eine der ersten Produktgruppen, die dieses Medium schon früh genutzt haben, um die Kommunikation zu fördern. Ein Blog hat nämlich für die Autoren als auch die Nutzer viele nette Vorteile:

Sie sehen also, es gibt ganz viele Argumente für ein Blog, selbst wenn Sie schon ein anderes Dokumentationssystem haben. Natürlich macht das ganze nur Sinn, wenn es auch "Consumer" gibt, also Personen die die erstellten Artikel lesen. Für sich alleine können Sie auch mit einer Sammlung von Notepad-Dateien weiter machen, wenn sie denn überhaupt dokumentieren.

Ich kann Sie aber nur auffordern, zu dokumentieren. Es muss kein Buch sein, aber wir vergessen alle sehr schnell.

Welches "Blog" sie einsetzen, ist ihre Entscheidung. Ich kenne Firmen, die sogar "extern" (also bei Wordpress oder Windows Live) mit dem Blog gestartet sind und die Daten dann später erst nach intern gezogen haben, um sich am Anfang den Server und die Installation zu sparen. Mittelfristig werden Sie aber ein Blog lieber intern laufen lassen. Das kann Wortpress sein (Auch Microsoft stellt Windows Live Spaces wird auf Wordpress um). Aber auch die Windows Sharepoint Services haben entsprechende Funktionen. Interessant ist z.B., wenn der Anwender sich nicht getrennt anmelden muss, d.h. das Blog auf die Daten des Active Directory zurückgreift.

Plädoyer für Wiki

Nun sind sie vielleicht alle von einem Blog infiziert. Aber ehe Sie nun los eilen, sollten Sie noch eine Alternative oder Ergänzung betrachten.

Viele Dinge kann ein Wiki hier sehr viel besser. Denken Sie mal drüber nach. Es muss ja kein "Öffentliches Wiki" sein. Für einen Firmeneinsatz können Sie durchaus einige Einschränkungen vornehmen (z.B. bestimmte Browser unterstützen). Mit Sharepoint könnte sogar ein "Rich-Client wie der Sharepoint Designer zum Einsatz kommen

Auf der anderen Seite sollte ein Unternehmens-Wiki auf jeden Fall die Identitätsverwaltung aus dem vorhandenen Verzeichnis und Anmeldedienst (z.B. Active Directory) beziehen und ein Single-SignOn unterstützen. Wenn eh schon alles "intern" ist, dann könnte jeder Abschnitt auch einen "Owner" haben, der bei Änderungen anderer Benutzer eine Nachricht erhält.

Es ist so viel denkbar, was ein Wiki auf jeden Fall zur besseren Plattform als statische Dateien einer Textverarbeitung macht. Allerdings bleibt es eine Webseite die auf einem Server an einem Ort abgelegt ist. Die wenigsten Wiki-Systeme erlauben eine Replikation oder einen Offline-Betrieb, was für eine IT-Dokumentation mit Desasterhandbuch nicht hilfreich ist. Ein Export als PDF oder ein statische Kopie (z.B. mit HTTrack) kann eine Option darstellen.

Tools zur automatischen Dokumentation

Es gibt zwar keine Tools, die Konzepte und Zusammenhänge automatisch erfassen aber reine System und Konfigurationsdaten können über verschiedene Hilfsprogramme sehr wohl erfasst und damit dokumentiert werden. Hier ein paar Links zu Tools.

Auch kommerzielle Werkzeuge helfen bei der Analyse und Dokumentation von Netzwerken Da ist in erste Reihe natürlich das GSTOOL vom BSI zu nennen. Zudem gibt es noch einige weitere kommerzielle Werkzeuge verschiedener Anbieter:

Es ist ja klar dass so eine Aufnahme nicht immer nur manuell erfolgen kann, so dass sich Systemhäuser natürlich selbst ihre Werkzeuge erstellen.

Es gibt als eine ganze Menge Werkzeuge, die auch Daten automatisch in eine solche Dokumentation einbauen können. Bedenken Sie aber, dass bestimmte Informationen auch besser in einem klassischen Inventarsystem (Softwareverteilung etc.) aufgehoben sind.

Viele Programme bringen "Assistenten" mit, die am Ende sogar eine "Zusammenfassung" ihrer Aktionen auf dem Bildschirm ausgeben. Leider gibt es innerhallb der Windows Plattform zwar APIs für alles mögliche aber eben keinen "Dokumentstore". Wäre es nicht genial, wenn diese Assistenten ihre Arbeit quasi "Auto-Doumentieren" könnten ?. So bleibt ihnen nur die manuelle Übertragung der Ausgaben in eine Dokumentation

Weitere Links

Keywords:Dokumentation