Document IT!

Wozu dokumentieren?

Informatiker sind auch nur Menschen. Sie vergessen Dinge, gehen in die Ferien, werden krank, wechseln den Arbeitgeber und haben Unfälle. Für einen solchen Fall muss man vorbereitet sein. Man muss also dokumentieren - aber wie?

Dem Zielpublikum gerecht werden

Eine Dokumentation soll dem Leser eine Übersicht verschaffen und ein Verständnis für Zusammenhänge vermitteln. Prozesse oder Einstellungen sollen nachvollziehbar werden. Eine Dokumentation hat immer ein bestimmtes Zielpublikum, das gewisse Voraussetzungen mitbringt und einen bestimmten Anspruch hat:

• Neue Mitarbeiter die sich einarbeiten.
• Fachkundige Mitarbeiter die spezifische Informationen brauchen.
• Der Autor selbst, der nicht alles im Kopf speichern kann.
• usw.

Die Dokumentation soll dem Anspruch des Lesers gerecht werden. Wenn ich einem Informatiker die Konfiguration eines Webserver erklären möchte, muss ich ja nicht bei der binären Arithmetik beginnen. Eine Dokumentation soll nicht Selbstzweck sein, es braucht also keine Facharbeit wo sich der Autor bloss profilieren möchte.

Zugänglichkeit

Einfache Prozesse und gute Werkzeuge fördern die Dokumentierfreude der Informatiker. Dokumentationen sollen einfach zugänglich und leicht anpassbar sein. Dabei kann der Zugang über ein Web Interface, eine strukturierte Ablage oder eine Suche helfen. Nun kommen die weiteren Ansprüche: Versionsverwaltung, Zugriffsrechte usw. Es gibt eine ganze Anzahl von Dokumenten- Managements, die alle diese und noch weitere Anforderungen erfüllen. Reicht aber vielleicht auch ein Wiki? Womit dokumentiert wird ist letztlich zweitrangig. Das Werkzeug soll so handhabbar sein, dass man sich auf das Werkstück konzentrieren kann.

Bilder

Diagramme geben viel Arbeit, können aber einen komplexen Sachverhalt sehr gut erklären. Screenshots brauchen etwas viel Speicherplatz  - ist das heute noch ein Argument um darauf zu verzichten?

Automatisierung

Vielerorts lässt sich die Dokumentation automatisieren. Informationen die dokumentiert werden sollen, sind meist bereits in einem System vorhanden: Hardwareinformationen, Netzwerkkonfigurationen usw. Sie lassen sich durch Skripts sammeln und aufbereiten. Aber Vorsicht. Sie bilden nur den Ist-Zustand ab und ersetzen natürlich nicht die Spezifikation.

Verfügbarkeit

Was, wenn der Arzt krank ist oder wenn es bei der Feuerwehr brennt? Soll die Dokumentation in einem Fehlerfall Hilfe leisten, nützt sie nichts wenn sie selbst vom Fehler betroffen ist. Eine gewisse Redundanz ist nötig. Eine Textdatei könnte beispielsweise einerseits auf einem Dateisystem abgelegt sein und zusätzlich als PDF-Version auf einer unabhängigen Web Applikation. Ein Netzwerklayout kann durchaus auch mal auch in Papierform vorhanden sein und den Arbeitsplatz dekorieren.

Es gibt nichts Gutes…

Die Dokumentation muss ja nicht gleich ein neues Standardwerk der Literaturgeschichte werden. Im Gegenteil: Manchmal ist weniger mehr - aber nichts bleibt nichts.