Nachdem ich letztens in einem Meeting den Hattrick im „Salz in die Wunde“ streuen geschafft habe, als ich auf die Frage ab wann ein System als produktiv gilt geantwortet habe: „Sobald es dokumentiert ist, gesichert und überwacht wird“, wollte ich mich diesmal dem Thema Dokumentation annehmen. Eigentlich ein simples Thema (das für mich zu jedem Projekt dazugehört) kann hier doch viel schief laufen.
Der Inhalt ist meist die einfachste Hürde. Hier hilft es sich im Vorfeld einfach über Zielgruppe und Ziel einig zu sein. Der Unterschied beispielsweise zwischen Installationsdokumentation für den Administrator oder Betriebshandbuch für die Hotline ist doch relativ groß. Bei der Installationsdokumentation sammelte ich üblicherweise nur die ausgeführten Befehle in Themenblöcken und erkläre nur grob warum und wieso, da grundsätzliche Kenntnisse der Funktion vom Linuxadministrator erwarte. Ein Betriebshandbuch ist dagegen ein ganz andere Sache, notfalls fange ich sogar mit Erklärungen an was den Linux überhaupt so ist und sammle Screenshots zu den wichtigsten graphischen Funktionen. Was ich auf alle Fälle allerdings vermeide ist es frei verfügbare Dokumentation unnötig zu duplizieren. Die meisten „Open Source“-Projekte liefern auch hier sehr gute Arbeit ab und halten diese auch aktuell, was oftmals bei eigener Dokumentation nicht der Fall ist oder zumindest zusätzlichen Aufwand bedeutet. Warum dies meist so ist, soll das Hauptthema dieses Blogposts sein.
Denn im Gegensatz zum Inhalt der auch nachträglich angepasst und erweitert werden kann, lässt sich die Dokumentationsplattform nur schwer ändern. Aber sie ist in meinen Augen neben Zeit der Hauptgrund für schlechte Dokumentation. Zu oft sehe ich bei Kunden eine Sammlung unversionierter, strukturloser Word-Dokumente vergraben auf einem Dateiserver oder werde gar gezwungen Dokuemntation in dieser Form zu erstellen. Diesen Dokumenten fehlen dann naturgemäß ein Änderungshistorie, durch die nachvollziehbar ist was wann und warum an der Umgebung geändert wurde. Eine Suche über alle Dokumentationen ist dann automatisiert nicht möglich, da erst die Datei gefunden werden möchte, dann der Inhalt. Und dieser ist aufgrund der fehlenden Struktur auch in vielen Fällen nur schwer von jemand anderem als dem Ersteller nachzuvollziehen. Alles in allem sorgt dies meist dafür, dass Dokumentation nicht weiter gepflegt wird, Themen gar nicht oder mehrfach betrachtet werden, …
Natürlich lässt sich hier auch einiges verbessern und von den aufgezeigten Problemen lösen, dabei gibt es aber genau dafür eine weiträumig akzeptierte Lösung in Form der verschiedensten Wiki-Lösungen. Spätestens durch Wikipedia ist den meisten das Konzept vertraut und ich persönlich mag auch Mediawiki als Software sehr gerne. Kommerzielle Lösungen wie Confluence sind eventuell schneller eingerichtet und bieten auch Plugins um sie noch nach Bedarf zu erweitern, aber mit Mediawiki erhält man halt auch einen gewohnten Look-and-Feel. Aber egal welche Lösung Änderungshistorie, Versionierung und Suche erhält man dann schon mal automatisch. Struktur lässt sich mit Templates sehr gut vorgeben, wobei dies natürlich auch bei anderen Lösungen möglich wäre, aber meist komplizierter durchzusetzen. Außerdem besteht die Möglichkeit sehr einfach auf andere Themen zu verweisen. Bei Mediawiki sogar in Form von roten Wiki-Links, die für andere ein Hinweis sein sollten, dass hier noch Dokumentation zu erstellen ist.
Aber auch mit einer Wikisoftware lässt sich noch viel falsch machen. Beispielsweise sind restriktive Rechte auf einem Betriebssystem gut, auf einer Dokumentationsplattform empfinde ich diese als eher hinderlich. Das Argument dann keine Passwörter hinterlegen zu können, lasse ich nicht gelten, da Passwörter eh einem Ablauf unterliegen sollten und in einer Lösung gespeichert werden sollten die dies berücksichtigt. Es sollte mehr im Fokus stehen, dass mehr Nutzer auch Prüfung und Erweiterung der Dokumentation bedeutet. Export, Import und Datei-Anhänge sind ein weiteres Thema. Ein Word-Import um alte Dokumentation zu übernehmen halte ich für sinnvoll, Export sollte allerdings nur in unveränderliche Formate erfolgen und idealerweise sollten Anhänge natürlich nicht die eigentliche Dokumentation darstellen.
Erfahrungsgemäß sorgt aber ein Wiki als Dokumentationsplattform nach ein bisschen Einarbeitung und Gewöhnung immer für eine höhere Qualität. Vor allem wenn auch entsprechende Zeit für Dokumentation eingeplant wird und ein Mehrwert aufgezeigt werden kann. Erklärt man dem Admin oder Entwickler nämlich, dass das Operating ihn nicht mehr nachts rausklingeln muss, wenn sie anhand der Dokumentation selbstständig handeln können, wird dieser fast schon freiwillig dokumentieren. Integriert man Dokumentation dann noch in die Prozesse oder sogar in die sowieso schon genutzten Werkzeuge beispielsweise als Icinga Web 2 Modul, sind alle Nutzer noch leichter von der Sinnhaftigkeit zu überzeugen.
Und eine Zielgruppe darf heutzutage nicht vergessen werden: Externer Support. Dieser ist ähnlich zu sehen wie ein neuer Kollege, der sich einarbeiten soll. Auch dieser kann viel schneller reagieren wenn die Zugänge entsprechend dokumentiert und viel hochwertigeren Support leisten wenn er nicht nur auf Systeme sondern auch auf gut gepflegte Dokumentation Zugriff hat.
In dem Sinne viel Erfolg bei der Auswahl einer Wikisoftware als neuer Dokumentationsplattform und beim Dokumentieren der Umgebung.
0 Kommentare