Dokumentation ist alles

Als Systemadministrator gibt es tausend Gründe, warum man dokumentieren sollte. Nicht nur, damit auch andere Leute (z.B. Urlaubsvertretung) die Systeme bedienen können, sondern auch weil man sich nicht alles merken kann und will. Das bei Programmierern bekannte System DRY - Don't Repeat Yourself - gilt in meinen Augen genauso für Sysadmins. Und da wo es keinen Sinn macht einen Vorgang zu automatisieren, weil der Aufwand unproportional groß ist, hilft eine gute Dokumentation dabei, dass man beim nächsten Mal alle Vorgänge anhand der Dokumentation abarbeiten kann, also ohne noch einmal Hirnschmalz zu investieren.

Da ich grade die Migration von meinem PowerBook auf mein neues MacBook Pro abgeschlossen habe, hatte ich die Idee, mal zu bloggen, wie ich meine Dokumentationen anfertige und pflege, denn die Migration meines Dokumenationssystems war sehr einfach.

Wie ich dokumentiere

Was sich bei mir seit Jahren bewährt hat ist ein lokales Wiki. Früher habe ich Dokumentationen in LaTeX angefertigt, ein großes PDF pro System. Das sieht am Ende schön aus, aber ist sehr unflexibel und auf dauer nicht pflegbar. Eine Systemdokumentation ist immer ein lebendiges Dokument und deshalb sollte das Hauptaugenmerkt auf leichte editiertbarkeit gelegt werden. Um so weniger Hürden man sich selbst in den Weg stellt um so hochwertiger werden die Dokumentationen. Ein Wiki ist im Prinzip eine Webanwendung in der man sehr einfach Seiten anlegen und editieren und verlinken kann (mehr Infos) und eignet sich deshalb ideal.

Nur wenn das Erstellen der Dokumentation einfach ist, kann es zeitnah erfolgen und das ist wichtig, denn oft hat man schon wenige Stunden nach einer kniffeligen Konfiguration wieder einen entscheiden Punkt oder eine wichtige Reihenfolge vergessen (besonders dann, wenn viel Ausprobieren angesagt war ...).

Als Systemadministrator weiß ich "Ein gutes System dokumentiert sich selbst", aber das reicht nicht. Muss man im Desasterfall das System wieder herstellen, hat man verloren, da die Dokumentation mit dem System selbst verloren ist. Oder hat jemand eine undokumentierte Änderung am System vorgenommen, so kann diese im schlimmsten Fall auch nicht mehr korrekt nachvollzogen werden, wenn es keine saubere Dokumentation des SOLL-Zustandes gibt.

Meine Anforderungen / Wünsche an ein Dokumentationssystem sind wie folgt:

Dokumentieren sollte einfach sein
Dokumentation sollte zeitnah erfolgen
Dokumentation sollte schnell gehen
Dokumentation darf systemnah sein

Wenn sich ein System sowieso selbst dokumentiert, wie kann dann eine gute Dokumentation aussehen?

Meine Dokumentationen sehen oft nicht anders aus als Auszüge aus der .bash_history zusammen mit Listings oder Diffs von Konfigurations-Dateien und einigen Erklärungen dazu. Zum Beispiel warum eine bestimmte Version einer Software eingesetzt werden musste oder dergleichen. Im Prinzip schreibe ich zusätzliche Erklärungen nur dort auf, wo nicht aus der Konfiguration zu erkennen ist warum etwas so gemacht wurde. So spare ich Zeit und halte den Umfang gering. Wenn das Dokumentieren schnell geht, hilft es mir die Lust nicht gleich wieder zu verlieren und wenn der Umfang gering bleibt kann ich die Dokumentation auch in ein paar Monaten noch schnell überfliegen und verstehen. (Viel einfacher als die alten 50-Seiten PDFs)

Auswahl einer Wiki Software

Ich hatte nicht wirklich viele Anforderungen an eine Wiki Software als ich angefangen habe dieses Dokumentationsprinzip zu nutzen. Wichtig war mir auf jeden Fall, dass keine Datenbank benötigt wird. Ein Wiki was nur auf Textdateien basiert ist leichter zu sichern und zu migrieren. Und da ich es nur alleine und lokal nutze spielt performance nun wirklich keine Rolle. Meine Entscheidung fiel auf DokuWiki, in PHP geschrieben und auch sonst alle Anforderungen erfüllend ist DokuWiki ein guter Kandidat für DokumentationsWikis (wie der Name ja schon nahe legt). Des Weiteren bietet DokuWiki eine einfache Syntax und Syntax-Highlighting für Code-Listings, was sicherlich sehr interessant ist, da ein Großteil der Dokumentationen aus Code-Listings bestehen wird.

Notizen zur Einrichtung auf einem Mac

Hier will ich nicht zu sehr ins Detail gehen. Zum einen hat nicht unbedingt jeder einen Mac zum anderen hat jeder seine eigenen Präferenzen. Des Weiteren habe ich den Vorgang fast so schon einmal beschrieben. Deshalb nur ein paar Notizen:

In der Datei /etc/httpd/httpd.conf wird PHP aktiviert:

LoadModule php4_module    libexec/httpd/libphp4.so
AddModule mod_php4.c

Immer noch in der Datei /etc/httpd/httpd.conf wird ein Directory-Container angelegt, der sicherstellt, dass das Wiki nur lokal (vom Rechner selbst) aus benutzt werden, denn vielleicht speichern wir auch sensitive Informationen, die nicht für jeden User im selben Netzwerk zugänglich sein sollen:
```
<Directory "/Library/WebServer/Documents/wiki">
        Order allow,deny
        Allow from 127.0.0.1
</Directory>
```
Die Wiki Software wird nun unter /Library/WebServer/Documents/wiki entpackt und ist damit schon fertig installiert.
Unter Systemeinstellungen > Sharing > Personal Web Sharing aktivieren. Dadurch wird der im OS X integrierte Apache Webserver gestartet. Das Wiki sollte nun unter http://127.0.0.1/wiki/ erreichbar sein.

Mehr Informationen

Wer noch mehr zum Thema Dokumentation wissen möchte, bzw. sich dafür interessiert, wie man sich das Leben als Systemadministrator etwas leichter machen kann, dem kann ich nur das Buch Time Management for System Administrators von Tom Limoncelli empfehlen. Ich habe das Buch vor ungefähr einem Jahr gelesen und profitiere bis heute noch davon.

Time Management

Veröffentlicht von Arne Brodowski am 30. Juli 2007, 13:06 in buch, dokumentation, dokuwiki, mac, mac os x, my best practices, sysadmin, time management, wiki.

Kommentare

frage eines menschen der gerade erst anfängt sich mit dem möglichen einsatz von WIKIS und im speziellen in organisationen zu beschäftigen: (ich hab mir dokuwiki angesehen und installiert und ein wenig in anleitungen herumgelesen)

- halten sie es für möglich dass dokuwiki als basis für wissensmanagement in einer organsiation verwendet wird, deren mitarbeiterInnen über geringes wissen im IT bereich verfügen, ohne den aufwand durch externe technikbetreuung wesentlich zu erhöhen?

- soweit ich gesehen habe lässt sich die konfiguration von rechten von userInnen nur über das editieren von files mittels eines ftp programmes bewerkstelligen, oder sehe ich das falsch? (und es gibt zb entsprechende erweiterungen in richting einer webbasierten administrationsoberfläche?)

- hat nicht auch der wysiwig editor seine grenzen - zb bei tabellen - und ist das lernen dieser befehle für relativ ungeübte userInnen nicht schwer?

- vielleicht verfälscht meine jahrelange erfahrung mit html grundbefehlen und vor allem mit blogs ein wenig:
aber mir kommt es so vor als ob die bedienung und vor allem die administration von blogsoftware wesentlich einfacher ist, als dokuwiki.

- für alles was sich ändert ist ein wiki fraglos die bessere lösung. aber ist nicht zum publizieren - auch zum strukturierten publizieren - ein blog das userfreundlichere angebot?

- und wie ist das im vergleich blog - dokuwiki mit der zugangsverwaltung (für interne seiten)

darf ich sie um ihre meinung dazu bitten.

herzlichen dank

manfred schindler

Geschrieben von manfred schindler 7 Monate, 2 Wochen nach Veröffentlichung des Blog-Eintrags am 16. März 2008, 15:23. Antworten
Hallo Herr Schindler, ich habe eine Antwort in folgendem Blog-Eintrag verfasst: http://www.arnebrodowski.de/blog/490-Blog-vs.-Wiki.html

Geschrieben von Arne 7 Monate, 2 Wochen nach Veröffentlichung des Blog-Eintrags am 17. März 2008, 13:01. Antworten